

<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>pymatgen.util package &mdash; pymatgen 2025.6.14 documentation</title>
      <link rel="stylesheet" type="text/css" href="assets/pygments.css?v=03e43079" />
      <link rel="stylesheet" type="text/css" href="assets/css/theme.css?v=e59714d7" />
      <link rel="stylesheet" type="text/css" href="assets/css/custom.css" />

  
    <link rel="canonical" href="https://pymatgen.orgpymatgen.util.html"/>
      <script src="assets/jquery.js?v=5d32c60e"></script>
      <script src="assets/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
      <script src="assets/documentation_options.js?v=03bec786"></script>
      <script src="assets/doctools.js?v=9bcbadda"></script>
      <script src="assets/sphinx_highlight.js?v=dc90522c"></script>
    <script src="assets/js/theme.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" /> 
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search"  style="background: linear-gradient(0deg, rgba(23,63,162,1) 0%, rgba(0,70,192,1) 100%)" >

          
          
          <a href="index.html">
            
          </a>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <!-- Local TOC -->
              <div class="local-toc"><ul>
<li><a class="reference internal" href="#">pymatgen.util package</a><ul>
<li><a class="reference internal" href="#submodules">Submodules</a></li>
<li><a class="reference internal" href="#module-pymatgen.util.coord">pymatgen.util.coord module</a><ul>
<li><a class="reference internal" href="#pymatgen.util.coord.Simplex"><code class="docutils literal notranslate"><span class="pre">Simplex</span></code></a><ul>
<li><a class="reference internal" href="#pymatgen.util.coord.Simplex.space_dim"><code class="docutils literal notranslate"><span class="pre">Simplex.space_dim</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.Simplex.simplex_dim"><code class="docutils literal notranslate"><span class="pre">Simplex.simplex_dim</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.Simplex.bary_coords"><code class="docutils literal notranslate"><span class="pre">Simplex.bary_coords()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.Simplex.coords"><code class="docutils literal notranslate"><span class="pre">Simplex.coords</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.Simplex.in_simplex"><code class="docutils literal notranslate"><span class="pre">Simplex.in_simplex()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.Simplex.line_intersection"><code class="docutils literal notranslate"><span class="pre">Simplex.line_intersection()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.Simplex.point_from_bary_coords"><code class="docutils literal notranslate"><span class="pre">Simplex.point_from_bary_coords()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.Simplex.volume"><code class="docutils literal notranslate"><span class="pre">Simplex.volume</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#pymatgen.util.coord.all_distances"><code class="docutils literal notranslate"><span class="pre">all_distances()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.barycentric_coords"><code class="docutils literal notranslate"><span class="pre">barycentric_coords()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.coord_list_mapping"><code class="docutils literal notranslate"><span class="pre">coord_list_mapping()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.coord_list_mapping_pbc"><code class="docutils literal notranslate"><span class="pre">coord_list_mapping_pbc()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.find_in_coord_list"><code class="docutils literal notranslate"><span class="pre">find_in_coord_list()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.find_in_coord_list_pbc"><code class="docutils literal notranslate"><span class="pre">find_in_coord_list_pbc()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.get_angle"><code class="docutils literal notranslate"><span class="pre">get_angle()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.get_linear_interpolated_value"><code class="docutils literal notranslate"><span class="pre">get_linear_interpolated_value()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.in_coord_list"><code class="docutils literal notranslate"><span class="pre">in_coord_list()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.in_coord_list_pbc"><code class="docutils literal notranslate"><span class="pre">in_coord_list_pbc()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.is_coord_subset"><code class="docutils literal notranslate"><span class="pre">is_coord_subset()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.is_coord_subset_pbc"><code class="docutils literal notranslate"><span class="pre">is_coord_subset_pbc()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.lattice_points_in_supercell"><code class="docutils literal notranslate"><span class="pre">lattice_points_in_supercell()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.pbc_diff"><code class="docutils literal notranslate"><span class="pre">pbc_diff()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord.pbc_shortest_vectors"><code class="docutils literal notranslate"><span class="pre">pbc_shortest_vectors()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-pymatgen.util.coord_cython">pymatgen.util.coord_cython module</a><ul>
<li><a class="reference internal" href="#pymatgen.util.coord_cython.coord_list_mapping_pbc"><code class="docutils literal notranslate"><span class="pre">coord_list_mapping_pbc()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord_cython.is_coord_subset_pbc"><code class="docutils literal notranslate"><span class="pre">is_coord_subset_pbc()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.coord_cython.pbc_shortest_vectors"><code class="docutils literal notranslate"><span class="pre">pbc_shortest_vectors()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-pymatgen.util.due">pymatgen.util.due module</a><ul>
<li><a class="reference internal" href="#pymatgen.util.due.BibTeX"><code class="docutils literal notranslate"><span class="pre">BibTeX()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.due.Doi"><code class="docutils literal notranslate"><span class="pre">Doi()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.due.InactiveDueCreditCollector"><code class="docutils literal notranslate"><span class="pre">InactiveDueCreditCollector</span></code></a><ul>
<li><a class="reference internal" href="#pymatgen.util.due.InactiveDueCreditCollector.activate"><code class="docutils literal notranslate"><span class="pre">InactiveDueCreditCollector.activate()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.due.InactiveDueCreditCollector.active"><code class="docutils literal notranslate"><span class="pre">InactiveDueCreditCollector.active</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.due.InactiveDueCreditCollector.add"><code class="docutils literal notranslate"><span class="pre">InactiveDueCreditCollector.add()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.due.InactiveDueCreditCollector.cite"><code class="docutils literal notranslate"><span class="pre">InactiveDueCreditCollector.cite()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.due.InactiveDueCreditCollector.dcite"><code class="docutils literal notranslate"><span class="pre">InactiveDueCreditCollector.dcite()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.due.InactiveDueCreditCollector.dump"><code class="docutils literal notranslate"><span class="pre">InactiveDueCreditCollector.dump()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.due.InactiveDueCreditCollector.load"><code class="docutils literal notranslate"><span class="pre">InactiveDueCreditCollector.load()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#pymatgen.util.due.Text"><code class="docutils literal notranslate"><span class="pre">Text()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.due.Url"><code class="docutils literal notranslate"><span class="pre">Url()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-pymatgen.util.graph_hashing">pymatgen.util.graph_hashing module</a><ul>
<li><a class="reference internal" href="#pymatgen.util.graph_hashing.weisfeiler_lehman_graph_hash"><code class="docutils literal notranslate"><span class="pre">weisfeiler_lehman_graph_hash()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.graph_hashing.weisfeiler_lehman_subgraph_hashes"><code class="docutils literal notranslate"><span class="pre">weisfeiler_lehman_subgraph_hashes()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-pymatgen.util.io_utils">pymatgen.util.io_utils module</a><ul>
<li><a class="reference internal" href="#pymatgen.util.io_utils.clean_lines"><code class="docutils literal notranslate"><span class="pre">clean_lines()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.io_utils.micro_pyawk"><code class="docutils literal notranslate"><span class="pre">micro_pyawk()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-pymatgen.util.joblib">pymatgen.util.joblib module</a><ul>
<li><a class="reference internal" href="#pymatgen.util.joblib.set_python_warnings"><code class="docutils literal notranslate"><span class="pre">set_python_warnings()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.joblib.tqdm_joblib"><code class="docutils literal notranslate"><span class="pre">tqdm_joblib()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-pymatgen.util.misc">pymatgen.util.misc module</a><ul>
<li><a class="reference internal" href="#pymatgen.util.misc.is_np_dict_equal"><code class="docutils literal notranslate"><span class="pre">is_np_dict_equal()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-pymatgen.util.num">pymatgen.util.num module</a><ul>
<li><a class="reference internal" href="#pymatgen.util.num.make_symmetric_matrix_from_upper_tri"><code class="docutils literal notranslate"><span class="pre">make_symmetric_matrix_from_upper_tri()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.num.round_to_sigfigs"><code class="docutils literal notranslate"><span class="pre">round_to_sigfigs()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-pymatgen.util.numba">pymatgen.util.numba module</a><ul>
<li><a class="reference internal" href="#pymatgen.util.numba.jit"><code class="docutils literal notranslate"><span class="pre">jit()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.numba.njit"><code class="docutils literal notranslate"><span class="pre">njit()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-pymatgen.util.plotting">pymatgen.util.plotting module</a><ul>
<li><a class="reference internal" href="#pymatgen.util.plotting.add_fig_kwargs"><code class="docutils literal notranslate"><span class="pre">add_fig_kwargs()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.plotting.format_formula"><code class="docutils literal notranslate"><span class="pre">format_formula()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.plotting.get_ax3d_fig"><code class="docutils literal notranslate"><span class="pre">get_ax3d_fig()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.plotting.get_ax_fig"><code class="docutils literal notranslate"><span class="pre">get_ax_fig()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.plotting.get_axarray_fig_plt"><code class="docutils literal notranslate"><span class="pre">get_axarray_fig_plt()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.plotting.periodic_table_heatmap"><code class="docutils literal notranslate"><span class="pre">periodic_table_heatmap()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.plotting.pretty_plot"><code class="docutils literal notranslate"><span class="pre">pretty_plot()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.plotting.pretty_plot_two_axis"><code class="docutils literal notranslate"><span class="pre">pretty_plot_two_axis()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.plotting.pretty_polyfit_plot"><code class="docutils literal notranslate"><span class="pre">pretty_polyfit_plot()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.plotting.van_arkel_triangle"><code class="docutils literal notranslate"><span class="pre">van_arkel_triangle()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-pymatgen.util.provenance">pymatgen.util.provenance module</a><ul>
<li><a class="reference internal" href="#pymatgen.util.provenance.Author"><code class="docutils literal notranslate"><span class="pre">Author</span></code></a><ul>
<li><a class="reference internal" href="#pymatgen.util.provenance.Author.as_dict"><code class="docutils literal notranslate"><span class="pre">Author.as_dict()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.provenance.Author.email"><code class="docutils literal notranslate"><span class="pre">Author.email</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.provenance.Author.from_dict"><code class="docutils literal notranslate"><span class="pre">Author.from_dict()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.provenance.Author.name"><code class="docutils literal notranslate"><span class="pre">Author.name</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.provenance.Author.parse_author"><code class="docutils literal notranslate"><span class="pre">Author.parse_author()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#pymatgen.util.provenance.HistoryNode"><code class="docutils literal notranslate"><span class="pre">HistoryNode</span></code></a><ul>
<li><a class="reference internal" href="#pymatgen.util.provenance.HistoryNode.name"><code class="docutils literal notranslate"><span class="pre">HistoryNode.name</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.provenance.HistoryNode.url"><code class="docutils literal notranslate"><span class="pre">HistoryNode.url</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.provenance.HistoryNode.description"><code class="docutils literal notranslate"><span class="pre">HistoryNode.description</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.provenance.HistoryNode.as_dict"><code class="docutils literal notranslate"><span class="pre">HistoryNode.as_dict()</span></code></a></li>
<li><a class="reference internal" href="#id0"><code class="docutils literal notranslate"><span class="pre">HistoryNode.description</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.provenance.HistoryNode.from_dict"><code class="docutils literal notranslate"><span class="pre">HistoryNode.from_dict()</span></code></a></li>
<li><a class="reference internal" href="#id7"><code class="docutils literal notranslate"><span class="pre">HistoryNode.name</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.provenance.HistoryNode.parse_history_node"><code class="docutils literal notranslate"><span class="pre">HistoryNode.parse_history_node()</span></code></a></li>
<li><a class="reference internal" href="#id8"><code class="docutils literal notranslate"><span class="pre">HistoryNode.url</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#pymatgen.util.provenance.StructureNL"><code class="docutils literal notranslate"><span class="pre">StructureNL</span></code></a><ul>
<li><a class="reference internal" href="#pymatgen.util.provenance.StructureNL.as_dict"><code class="docutils literal notranslate"><span class="pre">StructureNL.as_dict()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.provenance.StructureNL.from_dict"><code class="docutils literal notranslate"><span class="pre">StructureNL.from_dict()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.provenance.StructureNL.from_structures"><code class="docutils literal notranslate"><span class="pre">StructureNL.from_structures()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#pymatgen.util.provenance.is_valid_bibtex"><code class="docutils literal notranslate"><span class="pre">is_valid_bibtex()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-pymatgen.util.string">pymatgen.util.string module</a><ul>
<li><a class="reference internal" href="#pymatgen.util.string.Stringify"><code class="docutils literal notranslate"><span class="pre">Stringify</span></code></a><ul>
<li><a class="reference internal" href="#pymatgen.util.string.Stringify.STRING_MODE"><code class="docutils literal notranslate"><span class="pre">Stringify.STRING_MODE</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.string.Stringify.to_html_string"><code class="docutils literal notranslate"><span class="pre">Stringify.to_html_string()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.string.Stringify.to_latex_string"><code class="docutils literal notranslate"><span class="pre">Stringify.to_latex_string()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.string.Stringify.to_pretty_string"><code class="docutils literal notranslate"><span class="pre">Stringify.to_pretty_string()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.string.Stringify.to_unicode_string"><code class="docutils literal notranslate"><span class="pre">Stringify.to_unicode_string()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#pymatgen.util.string.charge_string"><code class="docutils literal notranslate"><span class="pre">charge_string()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.string.disordered_formula"><code class="docutils literal notranslate"><span class="pre">disordered_formula()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.string.formula_double_format"><code class="docutils literal notranslate"><span class="pre">formula_double_format()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.string.htmlify"><code class="docutils literal notranslate"><span class="pre">htmlify()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.string.latexify"><code class="docutils literal notranslate"><span class="pre">latexify()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.string.latexify_spacegroup"><code class="docutils literal notranslate"><span class="pre">latexify_spacegroup()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.string.str_delimited"><code class="docutils literal notranslate"><span class="pre">str_delimited()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.string.stream_has_colors"><code class="docutils literal notranslate"><span class="pre">stream_has_colors()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.string.transformation_to_string"><code class="docutils literal notranslate"><span class="pre">transformation_to_string()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.string.unicodeify"><code class="docutils literal notranslate"><span class="pre">unicodeify()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.string.unicodeify_spacegroup"><code class="docutils literal notranslate"><span class="pre">unicodeify_spacegroup()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.string.unicodeify_species"><code class="docutils literal notranslate"><span class="pre">unicodeify_species()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-pymatgen.util.testing">pymatgen.util.testing module</a><ul>
<li><a class="reference internal" href="#pymatgen.util.testing.MatSciTest"><code class="docutils literal notranslate"><span class="pre">MatSciTest</span></code></a><ul>
<li><a class="reference internal" href="#pymatgen.util.testing.MatSciTest.TEST_STRUCTURES"><code class="docutils literal notranslate"><span class="pre">MatSciTest.TEST_STRUCTURES</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.testing.MatSciTest.assert_msonable"><code class="docutils literal notranslate"><span class="pre">MatSciTest.assert_msonable()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.testing.MatSciTest.assert_str_content_equal"><code class="docutils literal notranslate"><span class="pre">MatSciTest.assert_str_content_equal()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.testing.MatSciTest.get_structure"><code class="docutils literal notranslate"><span class="pre">MatSciTest.get_structure()</span></code></a></li>
<li><a class="reference internal" href="#pymatgen.util.testing.MatSciTest.serialize_with_pickle"><code class="docutils literal notranslate"><span class="pre">MatSciTest.serialize_with_pickle()</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#pymatgen.util.testing.PymatgenTest"><code class="docutils literal notranslate"><span class="pre">PymatgenTest</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#module-pymatgen.util.typing">pymatgen.util.typing module</a></li>
</ul>
</li>
</ul>
</div>
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu"  style="background: linear-gradient(0deg, rgba(23,63,162,1) 0%, rgba(0,70,192,1) 100%)" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="index.html">pymatgen</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content style-external-links">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
      <li class="breadcrumb-item active">pymatgen.util package</li>
      <li class="wy-breadcrumbs-aside">
              <a href="https://github.com/materialsproject/pymatgen/blob/master/docs_rst/pymatgen.util.rst" class="fa fa-github"> Edit on GitHub</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="module-pymatgen.util">
<span id="pymatgen-util-package"></span><h1>pymatgen.util package<a class="headerlink" href="#module-pymatgen.util" title="Link to this heading"></a></h1>
<p>The util package implements various utilities that are commonly used by various
packages.</p>
<section id="submodules">
<h2>Submodules<a class="headerlink" href="#submodules" title="Link to this heading"></a></h2>
</section>
<section id="module-pymatgen.util.coord">
<span id="pymatgen-util-coord-module"></span><h2>pymatgen.util.coord module<a class="headerlink" href="#module-pymatgen.util.coord" title="Link to this heading"></a></h2>
<p>Utilities for manipulating coordinates or list of coordinates, under periodic
boundary conditions or otherwise. Many of these are heavily vectorized in
numpy for performance.</p>
<dl class="py class">
<dt class="sig sig-object py" id="pymatgen.util.coord.Simplex">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">Simplex</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">coords</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/coord.py#L362-L484"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.Simplex" title="Link to this definition"></a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">MSONable</span></code></p>
<p>A generalized simplex object. See <a class="reference external" href="https://wikipedia.org/wiki/Simplex">https://wikipedia.org/wiki/Simplex</a>.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="pymatgen.util.coord.Simplex.space_dim">
<span class="sig-name descname"><span class="pre">space_dim</span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/util/coord.py"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.Simplex.space_dim" title="Link to this definition"></a></dt>
<dd><p>Dimension of the space. Usually, this is 1 more than the simplex_dim.</p>
<dl class="field-list simple">
<dt class="field-odd">Type<span class="colon">:</span></dt>
<dd class="field-odd"><p>int</p>
</dd>
</dl>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="pymatgen.util.coord.Simplex.simplex_dim">
<span class="sig-name descname"><span class="pre">simplex_dim</span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/util/coord.py"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.Simplex.simplex_dim" title="Link to this definition"></a></dt>
<dd><p>Dimension of the simplex coordinate space.</p>
<dl class="field-list simple">
<dt class="field-odd">Type<span class="colon">:</span></dt>
<dd class="field-odd"><p>int</p>
</dd>
</dl>
</dd></dl>

<p>Initialize a Simplex from vertex coordinates.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>coords</strong> (<em>[</em><em>[</em><em>float</em><em>]</em><em>]</em>) – Coords of the vertices of the simplex. e.g.
[[1, 2, 3], [2, 4, 5], [6, 7, 8], [8, 9, 10].</p>
</dd>
</dl>
<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.coord.Simplex.bary_coords">
<span class="sig-name descname"><span class="pre">bary_coords</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">point</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/coord.py#L390-L401"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.Simplex.bary_coords" title="Link to this definition"></a></dt>
<dd><dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>point</strong> (<em>ArrayLike</em>) – Point coordinates.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Barycentric coordinations.</p>
</dd>
</dl>
</dd></dl>

<dl class="py property">
<dt class="sig sig-object py" id="pymatgen.util.coord.Simplex.coords">
<em class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">coords</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">ndarray</span></em><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/util/coord.py"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.Simplex.coords" title="Link to this definition"></a></dt>
<dd><p>A copy of the vertex coordinates in the simplex.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.coord.Simplex.in_simplex">
<span class="sig-name descname"><span class="pre">in_simplex</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">point</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Sequence</span><span class="p"><span class="pre">[</span></span><span class="pre">float</span><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tolerance</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">1e-08</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">bool</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/coord.py#L416-L431"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.Simplex.in_simplex" title="Link to this definition"></a></dt>
<dd><p>Check if a point is in the simplex using the standard barycentric
coordinate system algorithm.</p>
<p>Taking an arbitrary vertex as an origin, we compute the basis for the
simplex from this origin by subtracting all other vertices from the
origin. We then project the point into this coordinate system and
determine the linear decomposition coefficients in this coordinate
system. If the coeffs satisfy all(coeffs &gt;= 0), the composition
is in the facet.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>point</strong> (<em>list</em><em>[</em><em>float</em><em>]</em>) – Point to test</p></li>
<li><p><strong>tolerance</strong> (<em>float</em>) – Tolerance to test if point is in simplex.</p></li>
</ul>
</dd>
</dl>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.coord.Simplex.line_intersection">
<span class="sig-name descname"><span class="pre">line_intersection</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">point1</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Sequence</span><span class="p"><span class="pre">[</span></span><span class="pre">float</span><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="n"><span class="pre">point2</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Sequence</span><span class="p"><span class="pre">[</span></span><span class="pre">float</span><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tolerance</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">1e-08</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/coord.py#L433-L466"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.Simplex.line_intersection" title="Link to this definition"></a></dt>
<dd><p>Compute the intersection points of a line with a simplex.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>point1</strong> (<em>Sequence</em><em>[</em><em>float</em><em>]</em>) – 1st point to determine the line.</p></li>
<li><p><strong>point2</strong> (<em>Sequence</em><em>[</em><em>float</em><em>]</em>) – 2nd point to determine the line.</p></li>
<li><p><strong>tolerance</strong> (<em>float</em>) – Tolerance for checking if an intersection is in the simplex. Defaults to 1e-8.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>points where the line intersects the simplex (0, 1, or 2).</p>
</dd>
</dl>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.coord.Simplex.point_from_bary_coords">
<span class="sig-name descname"><span class="pre">point_from_bary_coords</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">bary_coords</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ArrayLike</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/coord.py#L403-L414"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.Simplex.point_from_bary_coords" title="Link to this definition"></a></dt>
<dd><dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>bary_coords</strong> (<em>ArrayLike</em>) – Barycentric coordinates (d+1, d).</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Point in the simplex.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>np.array</p>
</dd>
</dl>
</dd></dl>

<dl class="py property">
<dt class="sig sig-object py" id="pymatgen.util.coord.Simplex.volume">
<em class="property"><span class="k"><span class="pre">property</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">volume</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">float</span></em><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/util/coord.py"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.Simplex.volume" title="Link to this definition"></a></dt>
<dd><p>Volume of the simplex.</p>
</dd></dl>

</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.coord.all_distances">
<span class="sig-name descname"><span class="pre">all_distances</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">coords1</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ArrayLike</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">coords2</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ArrayLike</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">np.ndarray</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/coord.py#L147-L161"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.all_distances" title="Link to this definition"></a></dt>
<dd><p>Get the distances between two lists of coordinates.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>coords1</strong> – First set of Cartesian coordinates.</p></li>
<li><p><strong>coords2</strong> – Second set of Cartesian coordinates.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>2d array of Cartesian distances. E.g the distance between
coords1[i] and coords2[j] is distances[i,j]</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.coord.barycentric_coords">
<span class="sig-name descname"><span class="pre">barycentric_coords</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">coords</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">simplex</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/coord.py#L320-L337"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.barycentric_coords" title="Link to this definition"></a></dt>
<dd><p>Convert a list of coordinates to barycentric coordinates, given a
simplex with d+1 points. Only works for d &gt;= 2.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>coords</strong> – list of n coords to transform, shape should be (n,d)</p></li>
<li><p><strong>simplex</strong> – list of coordinates that form the simplex, shape should be
(d+1, d)</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>a list of barycentric coordinates (even if the original input was 1d)</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.coord.coord_list_mapping">
<span class="sig-name descname"><span class="pre">coord_list_mapping</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">subset</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ArrayLike</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">superset</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ArrayLike</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">atol</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">1e-08</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/coord.py#L80-L100"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.coord_list_mapping" title="Link to this definition"></a></dt>
<dd><p>Get the index mapping from a subset to a superset.
Subset and superset cannot contain duplicate rows.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>subset</strong> (<em>ArrayLike</em>) – List of coords</p></li>
<li><p><strong>superset</strong> (<em>ArrayLike</em>) – List of coords</p></li>
<li><p><strong>atol</strong> (<em>float</em>) – Absolute tolerance. Defaults to 1e-8.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>list of indices such that superset[indices] = subset</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.coord.coord_list_mapping_pbc">
<span class="sig-name descname"><span class="pre">coord_list_mapping_pbc</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">subset</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">superset</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">atol</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">1e-08</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pbc</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">tuple</span><span class="p"><span class="pre">[</span></span><span class="pre">bool</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">bool</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">bool</span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">(True,</span> <span class="pre">True,</span> <span class="pre">True)</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/coord.py#L103-L117"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.coord_list_mapping_pbc" title="Link to this definition"></a></dt>
<dd><p>Get the index mapping from a subset to a superset.
Superset cannot contain duplicate matching rows.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>subset</strong> (<em>ArrayLike</em>) – List of frac_coords</p></li>
<li><p><strong>superset</strong> (<em>ArrayLike</em>) – List of frac_coords</p></li>
<li><p><strong>atol</strong> (<em>float</em>) – Absolute tolerance. Defaults to 1e-8.</p></li>
<li><p><strong>pbc</strong> (<em>tuple</em>) – A tuple defining the periodic boundary conditions along the three
axis of the lattice.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>list of indices such that superset[indices] = subset</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.coord.find_in_coord_list">
<span class="sig-name descname"><span class="pre">find_in_coord_list</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">coord_list</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">coord</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">atol</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">1e-08</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/coord.py#L28-L43"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.find_in_coord_list" title="Link to this definition"></a></dt>
<dd><p>Find the indices of matches of a particular coord in a coord_list.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>coord_list</strong> – List of coords to test</p></li>
<li><p><strong>coord</strong> – Specific coordinates</p></li>
<li><p><strong>atol</strong> – Absolute tolerance. Defaults to 1e-8. Accepts both scalar and
array.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Indices of matches, e.g. [0, 1, 2, 3]. Empty list if not found.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.coord.find_in_coord_list_pbc">
<span class="sig-name descname"><span class="pre">find_in_coord_list_pbc</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">frac_coord_list</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">frac_coord</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">atol</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">1e-08</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pbc</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">tuple</span><span class="p"><span class="pre">[</span></span><span class="pre">bool</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">bool</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">bool</span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">(True,</span> <span class="pre">True,</span> <span class="pre">True)</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">ndarray</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/coord.py#L208-L230"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.find_in_coord_list_pbc" title="Link to this definition"></a></dt>
<dd><p>Get the indices of all points in a fractional coord list that are
equal to a fractional coord (with a tolerance), taking into account
periodic boundary conditions.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>frac_coord_list</strong> – List of fractional coords</p></li>
<li><p><strong>frac_coord</strong> – A specific fractional coord to test.</p></li>
<li><p><strong>atol</strong> – Absolute tolerance. Defaults to 1e-8.</p></li>
<li><p><strong>pbc</strong> – a tuple defining the periodic boundary conditions along the three
axis of the lattice.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Indices of matches, e.g. [0, 1, 2, 3]. Empty list if not found.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.coord.get_angle">
<span class="sig-name descname"><span class="pre">get_angle</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">v1</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ArrayLike</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">v2</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ArrayLike</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">units</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Literal</span><span class="p"><span class="pre">[</span></span><span class="s"><span class="pre">'degrees'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'radians'</span></span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">'degrees'</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">float</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/coord.py#L340-L359"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.get_angle" title="Link to this definition"></a></dt>
<dd><p>Calculate the angle between two vectors.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>v1</strong> – Vector 1</p></li>
<li><p><strong>v2</strong> – Vector 2</p></li>
<li><p><strong>units</strong> – “degrees” or “radians”. Defaults to “degrees”.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Angle between them in degrees.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.coord.get_linear_interpolated_value">
<span class="sig-name descname"><span class="pre">get_linear_interpolated_value</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">x_values</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ArrayLike</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">y_values</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ArrayLike</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">x</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">float</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/coord.py#L120-L144"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.get_linear_interpolated_value" title="Link to this definition"></a></dt>
<dd><p>Get an interpolated value by linear interpolation between two values.
This method is written to avoid dependency on scipy, which causes issues on
threading servers.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>x_values</strong> – Sequence of x values.</p></li>
<li><p><strong>y_values</strong> – Corresponding sequence of y values</p></li>
<li><p><strong>x</strong> – Get value at particular x</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Value at x.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.coord.in_coord_list">
<span class="sig-name descname"><span class="pre">in_coord_list</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">coord_list</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">coord</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">atol</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">1e-08</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">bool</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/coord.py#L46-L58"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.in_coord_list" title="Link to this definition"></a></dt>
<dd><p>Test if a particular coord is within a coord_list.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>coord_list</strong> – List of coords to test</p></li>
<li><p><strong>coord</strong> – Specific coordinates</p></li>
<li><p><strong>atol</strong> – Absolute tolerance. Defaults to 1e-8. Accepts both scalar and
array.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>True if coord is in the coord list.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>bool</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.coord.in_coord_list_pbc">
<span class="sig-name descname"><span class="pre">in_coord_list_pbc</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fcoord_list</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fcoord</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">atol</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">1e-08</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pbc</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">tuple</span><span class="p"><span class="pre">[</span></span><span class="pre">bool</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">bool</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">bool</span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">(True,</span> <span class="pre">True,</span> <span class="pre">True)</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">bool</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/coord.py#L233-L248"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.in_coord_list_pbc" title="Link to this definition"></a></dt>
<dd><p>Test if a particular fractional coord is within a fractional coord_list.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>fcoord_list</strong> – List of fractional coords to test</p></li>
<li><p><strong>fcoord</strong> – A specific fractional coord to test.</p></li>
<li><p><strong>atol</strong> – Absolute tolerance. Defaults to 1e-8.</p></li>
<li><p><strong>pbc</strong> – a tuple defining the periodic boundary conditions along the three
axis of the lattice.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>True if coord is in the coord list.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>bool</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.coord.is_coord_subset">
<span class="sig-name descname"><span class="pre">is_coord_subset</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">subset</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ArrayLike</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">superset</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ArrayLike</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">atol</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">1e-08</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">bool</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/coord.py#L61-L77"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.is_coord_subset" title="Link to this definition"></a></dt>
<dd><p>Test if all coords in subset are contained in superset.
Doesn’t use periodic boundary conditions.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>subset</strong> (<em>ArrayLike</em>) – List of coords</p></li>
<li><p><strong>superset</strong> (<em>ArrayLike</em>) – List of coords</p></li>
<li><p><strong>atol</strong> (<em>float</em>) – Absolute tolerance for comparing coordinates. Defaults to 1e-8.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>True if all of subset is in superset.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>bool</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.coord.is_coord_subset_pbc">
<span class="sig-name descname"><span class="pre">is_coord_subset_pbc</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">subset</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">superset</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">atol</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">1e-08</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mask</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pbc</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">tuple</span><span class="p"><span class="pre">[</span></span><span class="pre">bool</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">bool</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">bool</span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">(True,</span> <span class="pre">True,</span> <span class="pre">True)</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">bool</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/coord.py#L251-L274"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.is_coord_subset_pbc" title="Link to this definition"></a></dt>
<dd><p>Test if all fractional coords in subset are contained in superset.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>subset</strong> (<em>list</em>) – List of fractional coords to test</p></li>
<li><p><strong>superset</strong> (<em>list</em>) – List of fractional coords to test against</p></li>
<li><p><strong>atol</strong> (<em>float</em><em> or </em><em>size 3 array</em>) – Tolerance for matching</p></li>
<li><p><strong>mask</strong> (<em>boolean array</em>) – Mask of matches that are not allowed.
i.e. if mask[1,2] is True, then subset[1] cannot be matched
to superset[2]</p></li>
<li><p><strong>pbc</strong> (<em>tuple</em>) – a tuple defining the periodic boundary conditions along the three
axis of the lattice.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>True if all of subset is in superset.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>bool</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.coord.lattice_points_in_supercell">
<span class="sig-name descname"><span class="pre">lattice_points_in_supercell</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">supercell_matrix</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/coord.py#L277-L317"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.lattice_points_in_supercell" title="Link to this definition"></a></dt>
<dd><p>Get the list of points on the original lattice contained in the
supercell in fractional coordinates (with the supercell basis).
e.g. [[2,0,0],[0,1,0],[0,0,1]] returns [[0,0,0],[0.5,0,0]].</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>supercell_matrix</strong> – 3x3 matrix describing the supercell</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>numpy array of the fractional coordinates</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.coord.pbc_diff">
<span class="sig-name descname"><span class="pre">pbc_diff</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">frac_coords1</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ArrayLike</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">frac_coords2</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ArrayLike</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pbc</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">tuple</span><span class="p"><span class="pre">[</span></span><span class="pre">bool</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">bool</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">bool</span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">(True,</span> <span class="pre">True,</span> <span class="pre">True)</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/coord.py#L164-L183"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.pbc_diff" title="Link to this definition"></a></dt>
<dd><p>Get the ‘fractional distance’ between two coordinates taking into
account periodic boundary conditions.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>frac_coords1</strong> – First set of fractional coordinates. e.g. [0.5, 0.6,
0.7] or [[1.1, 1.2, 4.3], [0.5, 0.6, 0.7]]. It can be a single
coord or any array of coords.</p></li>
<li><p><strong>frac_coords2</strong> – Second set of fractional coordinates.</p></li>
<li><p><strong>pbc</strong> – a tuple defining the periodic boundary conditions along the three
axis of the lattice.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Fractional distance. Each coordinate must have the property that
abs(a) &lt;= 0.5. Examples:
pbc_diff([0.1, 0.1, 0.1], [0.3, 0.5, 0.9]) = [-0.2, -0.4, 0.2]
pbc_diff([0.9, 0.1, 1.01], [0.3, 0.5, 0.9]) = [-0.4, -0.4, 0.11]</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.coord.pbc_shortest_vectors">
<span class="sig-name descname"><span class="pre">pbc_shortest_vectors</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">lattice</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">frac_coords1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">frac_coords2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mask</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">return_d2</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/coord.py#L186-L205"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord.pbc_shortest_vectors" title="Link to this definition"></a></dt>
<dd><p>Get the shortest vectors between two lists of coordinates taking into
account periodic boundary conditions and the lattice.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>lattice</strong> – lattice to use</p></li>
<li><p><strong>frac_coords1</strong> – First set of fractional coordinates. e.g. [0.5, 0.6, 0.7]
or [[1.1, 1.2, 4.3], [0.5, 0.6, 0.7]]. It can be a single
coord or any array of coords.</p></li>
<li><p><strong>frac_coords2</strong> – Second set of fractional coordinates.</p></li>
<li><p><strong>mask</strong> (<em>boolean array</em>) – Mask of matches that are not allowed.
i.e. if mask[1,2] is True, then subset[1] cannot be matched
to superset[2]</p></li>
<li><p><strong>return_d2</strong> (<em>bool</em>) – whether to also return the squared distances</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><dl class="simple">
<dt>of displacement vectors from frac_coords1 to frac_coords2</dt><dd><p>first index is frac_coords1 index, second is frac_coords2 index</p>
</dd>
</dl>
</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>np.ndarray</p>
</dd>
</dl>
</dd></dl>

</section>
<section id="module-pymatgen.util.coord_cython">
<span id="pymatgen-util-coord-cython-module"></span><h2>pymatgen.util.coord_cython module<a class="headerlink" href="#module-pymatgen.util.coord_cython" title="Link to this heading"></a></h2>
<p>Utilities for manipulating coordinates or list of coordinates, under periodic
boundary conditions or otherwise.</p>
<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.coord_cython.coord_list_mapping_pbc">
<span class="sig-name descname"><span class="pre">coord_list_mapping_pbc</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">subset</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">superset</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">atol</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1e-08</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pbc</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">(True,</span> <span class="pre">True,</span> <span class="pre">True)</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/util/coord_cython.py"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord_cython.coord_list_mapping_pbc" title="Link to this definition"></a></dt>
<dd><p>Gives the index mapping from a subset to a superset.
Superset cannot contain duplicate matching rows.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>subset</strong> – List of frac_coords.</p></li>
<li><p><strong>superset</strong> – List of frac_coords.</p></li>
<li><p><strong>pbc</strong> – a tuple defining the periodic boundary conditions along the three
axis of the lattice.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>list of indices such that superset[indices] = subset</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.coord_cython.is_coord_subset_pbc">
<span class="sig-name descname"><span class="pre">is_coord_subset_pbc</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">subset</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">superset</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">atol</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mask</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pbc</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">(True,</span> <span class="pre">True,</span> <span class="pre">True)</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/util/coord_cython.py"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord_cython.is_coord_subset_pbc" title="Link to this definition"></a></dt>
<dd><p>Tests if all fractional coords in subset are contained in superset.
Allows specification of a mask determining pairs that are not
allowed to match to each other.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>subset</strong> – List of fractional coords.</p></li>
<li><p><strong>superset</strong> – List of fractional coords.</p></li>
<li><p><strong>pbc</strong> – a tuple defining the periodic boundary conditions along the three
axis of the lattice.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>True if all of subset is in superset.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.coord_cython.pbc_shortest_vectors">
<span class="sig-name descname"><span class="pre">pbc_shortest_vectors</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">lattice</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fcoords1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fcoords2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mask</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">return_d2</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">lll_frac_tol</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/util/coord_cython.py"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.coord_cython.pbc_shortest_vectors" title="Link to this definition"></a></dt>
<dd><p>Get the shortest vectors between two lists of coordinates taking into
account periodic boundary conditions and the lattice.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>lattice</strong> – lattice to use</p></li>
<li><p><strong>fcoords1</strong> – First set of fractional coordinates. e.g., [0.5, 0.6, 0.7]
or [[1.1, 1.2, 4.3], [0.5, 0.6, 0.7]]. Must be np.float64</p></li>
<li><p><strong>fcoords2</strong> – Second set of fractional coordinates.</p></li>
<li><p><strong>mask</strong> (<a href="#id9"><span class="problematic" id="id10">int_</span></a> array) – Mask of matches that are not allowed.
i.e. if mask[1,2] == True, then subset[1] cannot be matched
to superset[2]</p></li>
<li><p><strong>lll_frac_tol</strong> (<a href="#id11"><span class="problematic" id="id12">float_</span></a> array of length 3) – Fractional tolerance (per LLL lattice vector) over which
the calculation of minimum vectors will be skipped.
Can speed up calculation considerably for large structures.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><dl class="simple">
<dt>of displacement vectors from fcoords1 to fcoords2</dt><dd><p>first index is fcoords1 index, second is fcoords2 index</p>
</dd>
</dl>
</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>np.array</p>
</dd>
</dl>
</dd></dl>

</section>
<section id="module-pymatgen.util.due">
<span id="pymatgen-util-due-module"></span><h2>pymatgen.util.due module<a class="headerlink" href="#module-pymatgen.util.due" title="Link to this heading"></a></h2>
<p>Stub file for a guaranteed safe import of duecredit constructs: if duecredit
is not available.</p>
<p>Then use in your code as</p>
<blockquote>
<div><p>from .due import due, Doi, BibTeX, Text</p>
</div></blockquote>
<p>See <a class="reference external" href="https://github.com/duecredit/duecredit/blob/master/README.md">https://github.com/duecredit/duecredit/blob/master/README.md</a> for examples.</p>
<p>Origin:     Originally a part of the duecredit
Copyright:  2015-2021 DueCredit developers
License:    BSD-2</p>
<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.due.BibTeX">
<span class="sig-name descname"><span class="pre">BibTeX</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/due.py#L43-L44"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.due.BibTeX" title="Link to this definition"></a></dt>
<dd><p>Perform no good and no bad.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.due.Doi">
<span class="sig-name descname"><span class="pre">Doi</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/due.py#L43-L44"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.due.Doi" title="Link to this definition"></a></dt>
<dd><p>Perform no good and no bad.</p>
</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="pymatgen.util.due.InactiveDueCreditCollector">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">InactiveDueCreditCollector</span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/due.py#L22-L40"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.due.InactiveDueCreditCollector" title="Link to this definition"></a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></p>
<p>Just a stub at the Collector which would not do anything.</p>
<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.due.InactiveDueCreditCollector.activate">
<span class="sig-name descname"><span class="pre">activate</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/due.py#L25-L26"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.due.InactiveDueCreditCollector.activate" title="Link to this definition"></a></dt>
<dd><p>Perform no good and no bad.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="pymatgen.util.due.InactiveDueCreditCollector.active">
<span class="sig-name descname"><span class="pre">active</span></span><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">False</span></em><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/util/due.py"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.due.InactiveDueCreditCollector.active" title="Link to this definition"></a></dt>
<dd></dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.due.InactiveDueCreditCollector.add">
<span class="sig-name descname"><span class="pre">add</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/due.py#L25-L26"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.due.InactiveDueCreditCollector.add" title="Link to this definition"></a></dt>
<dd><p>Perform no good and no bad.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.due.InactiveDueCreditCollector.cite">
<span class="sig-name descname"><span class="pre">cite</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/due.py#L25-L26"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.due.InactiveDueCreditCollector.cite" title="Link to this definition"></a></dt>
<dd><p>Perform no good and no bad.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.due.InactiveDueCreditCollector.dcite">
<span class="sig-name descname"><span class="pre">dcite</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/due.py#L28-L34"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.due.InactiveDueCreditCollector.dcite" title="Link to this definition"></a></dt>
<dd><p>If I could cite I would.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.due.InactiveDueCreditCollector.dump">
<span class="sig-name descname"><span class="pre">dump</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/due.py#L25-L26"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.due.InactiveDueCreditCollector.dump" title="Link to this definition"></a></dt>
<dd><p>Perform no good and no bad.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.due.InactiveDueCreditCollector.load">
<span class="sig-name descname"><span class="pre">load</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/due.py#L25-L26"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.due.InactiveDueCreditCollector.load" title="Link to this definition"></a></dt>
<dd><p>Perform no good and no bad.</p>
</dd></dl>

</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.due.Text">
<span class="sig-name descname"><span class="pre">Text</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/due.py#L43-L44"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.due.Text" title="Link to this definition"></a></dt>
<dd><p>Perform no good and no bad.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.due.Url">
<span class="sig-name descname"><span class="pre">Url</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/due.py#L43-L44"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.due.Url" title="Link to this definition"></a></dt>
<dd><p>Perform no good and no bad.</p>
</dd></dl>

</section>
<section id="module-pymatgen.util.graph_hashing">
<span id="pymatgen-util-graph-hashing-module"></span><h2>pymatgen.util.graph_hashing module<a class="headerlink" href="#module-pymatgen.util.graph_hashing" title="Link to this heading"></a></h2>
<p>Copyright (C) 2004-2022, NetworkX Developers
Aric Hagberg &lt;<a class="reference external" href="mailto:hagberg&#37;&#52;&#48;lanl&#46;gov">hagberg<span>&#64;</span>lanl<span>&#46;</span>gov</a>&gt;
Dan Schult &lt;<a class="reference external" href="mailto:dschult&#37;&#52;&#48;colgate&#46;edu">dschult<span>&#64;</span>colgate<span>&#46;</span>edu</a>&gt;
Pieter Swart &lt;<a class="reference external" href="mailto:swart&#37;&#52;&#48;lanl&#46;gov">swart<span>&#64;</span>lanl<span>&#46;</span>gov</a>&gt;
All rights reserved.</p>
<p>Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:</p>
<blockquote>
<div><ul class="simple">
<li><p>Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.</p></li>
<li><p>Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided
with the distribution.</p></li>
<li><p>Neither the name of the NetworkX Developers nor the names of its
contributors may be used to endorse or promote products derived
from this software without specific prior written permission.</p></li>
</ul>
</div></blockquote>
<p>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
“AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</p>
<hr class="docutils" />
<p>Functions for hashing graphs to strings.
Isomorphic graphs should be assigned identical hashes.
For now, only Weisfeiler-Lehman hashing is implemented.</p>
<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.graph_hashing.weisfeiler_lehman_graph_hash">
<span class="sig-name descname"><span class="pre">weisfeiler_lehman_graph_hash</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">graph</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">nx.Graph</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">edge_attr</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">node_attr</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">iterations</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">3</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">digest_size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">16</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/graph_hashing.py#L76-L148"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.graph_hashing.weisfeiler_lehman_graph_hash" title="Link to this definition"></a></dt>
<dd><p>Return Weisfeiler Lehman (WL) graph hash.</p>
<p>The function iteratively aggregates and hashes neighborhoods of each node.
After each node’s neighbors are hashed to obtain updated node labels,
a hashed histogram of resulting labels is returned as the final hash.</p>
<p>Hashes are identical for isomorphic graphs and strong guarantees that
non-isomorphic graphs will get different hashes. See <a href="#id13"><span class="problematic" id="id1">[1]_</span></a> for details.</p>
<p>If no node or edge attributes are provided, the degree of each node
is used as its initial label.
Otherwise, node and/or edge labels are used to compute the hash.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>graph</strong> – nx.Graph
The graph to be hashed.
Can have node and/or edge attributes. Can also have no attributes.</p></li>
<li><p><strong>edge_attr</strong> – string, default=None
The key in edge attribute dictionary to be used for hashing.
If None, edge labels are ignored.</p></li>
<li><p><strong>node_attr</strong> – string, default=None
The key in node attribute dictionary to be used for hashing.
If None, and no edge_attr given, use the degrees of the nodes as labels.</p></li>
<li><p><strong>iterations</strong> – int, default=3
Number of neighbor aggregations to perform.
Should be larger for larger graphs.</p></li>
<li><p><strong>digest_size</strong> – int, default=16
Size (in bits) of blake2b hash digest to use for hashing node labels.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><dl class="simple">
<dt>string</dt><dd><p>Hexadecimal string corresponding to hash of the input graph.</p>
</dd>
</dl>
</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>h</p>
</dd>
</dl>
<p class="rubric">Notes</p>
<p>To return the WL hashes of each subgraph of a graph, use
<cite>weisfeiler_lehman_subgraph_hashes</cite></p>
<p>Similarity between hashes does not imply similarity between graphs.</p>
<p class="rubric">References</p>
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="id2" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></span>
<p>Shervashidze, Nino, Pascal Schweitzer, Erik Jan Van Leeuwen,</p>
</aside>
</aside>
<p>Kurt Mehlhorn, and Karsten M. Borgwardt. Weisfeiler Lehman
Graph Kernels. Journal of Machine Learning Research. 2011.
<a class="reference external" href="https://www.jmlr.org/papers/volume12/shervashidze11a/shervashidze11a.pdf">https://www.jmlr.org/papers/volume12/shervashidze11a/shervashidze11a.pdf</a></p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p>weisfeiler_lehman_subgraph_hashes</p>
</div>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.graph_hashing.weisfeiler_lehman_subgraph_hashes">
<span class="sig-name descname"><span class="pre">weisfeiler_lehman_subgraph_hashes</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">graph</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">edge_attr</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">node_attr</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">iterations</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">3</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">digest_size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">16</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/graph_hashing.py#L151-L250"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.graph_hashing.weisfeiler_lehman_subgraph_hashes" title="Link to this definition"></a></dt>
<dd><p>Return a dictionary of subgraph hashes by node.</p>
<p>The dictionary is keyed by node to a list of hashes in increasingly
sized induced subgraphs containing the nodes within 2*k edges
of the key node for increasing integer k until all nodes are included.</p>
<p>The function iteratively aggregates and hashes neighborhoods of each node.
This is achieved for each step by replacing for each node its label from
the previous iteration with its hashed 1-hop neighborhood aggregate.
The new node label is then appended to a list of node labels for each
node.</p>
<p>To aggregate neighborhoods at each step for a node $n$, all labels of
nodes adjacent to $n$ are concatenated. If the <cite>edge_attr</cite> parameter is set,
labels for each neighboring node are prefixed with the value of this attribute
along the connecting edge from this neighbor to node $n$. The resulting string
is then hashed to compress this information into a fixed digest size.</p>
<p>Thus, at the $i$th iteration nodes within $2i$ distance influence any given
hashed node label. We can therefore say that at depth $i$ for node $n$
we have a hash for a subgraph induced by the $2i$-hop neighborhood of $n$.</p>
<p>Can be used to to create general Weisfeiler-Lehman graph kernels, or
generate features for graphs or nodes, for example to generate ‘words’ in a
graph as seen in the ‘graph2vec’ algorithm.
See <a href="#id14"><span class="problematic" id="id3">[1]_</span></a> &amp; <a href="#id15"><span class="problematic" id="id4">[2]_</span></a> respectively for details.</p>
<p>Hashes are identical for isomorphic subgraphs and there exist strong
guarantees that non-isomorphic graphs will get different hashes.
See <a href="#id16"><span class="problematic" id="id5">[1]_</span></a> for details.</p>
<p>If no node or edge attributes are provided, the degree of each node
is used as its initial label.
Otherwise, node and/or edge labels are used to compute the hash.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>graph</strong> – nx.Graph
The graph to be hashed.
Can have node and/or edge attributes. Can also have no attributes.</p></li>
<li><p><strong>edge_attr</strong> – string, default=None
The key in edge attribute dictionary to be used for hashing.
If None, edge labels are ignored.</p></li>
<li><p><strong>node_attr</strong> – string, default=None
The key in node attribute dictionary to be used for hashing.
If None, and no edge_attr given, use the degrees of the nodes as labels.</p></li>
<li><p><strong>iterations</strong> – int, default=3
Number of neighbor aggregations to perform.
Should be larger for larger graphs.</p></li>
<li><p><strong>digest_size</strong> – int, default=16
Size (in bits) of blake2b hash digest to use for hashing node labels.
The default size is 16 bits</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p><dl class="simple">
<dt>dict</dt><dd><p>A dictionary with each key given by a node in G, and each value given
by the subgraph hashes in order of depth from the key node.</p>
</dd>
</dl>
</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>node_subgraph_hashes</p>
</dd>
</dl>
<p class="rubric">Notes</p>
<p>To hash the full graph when subgraph hashes are not needed, use
<cite>weisfeiler_lehman_graph_hash</cite> for efficiency.</p>
<p>Similarity between hashes does not imply similarity between graphs.</p>
<p class="rubric">References</p>
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="id6" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></span>
<p>Shervashidze, Nino, Pascal Schweitzer, Erik Jan Van Leeuwen,</p>
</aside>
</aside>
<p>Kurt Mehlhorn, and Karsten M. Borgwardt. Weisfeiler Lehman
Graph Kernels. Journal of Machine Learning Research. 2011.
<a class="reference external" href="https://www.jmlr.org/papers/volume12/shervashidze11a/shervashidze11a.pdf">https://www.jmlr.org/papers/volume12/shervashidze11a/shervashidze11a.pdf</a>
.. [2] Annamalai Narayanan, Mahinthan Chandramohan, Rajasekar Venkatesan,
Lihui Chen, Yang Liu and Shantanu Jaiswa. graph2vec: Learning
Distributed Representations of Graphs. arXiv. 2017
<a class="reference external" href="https://arxiv.org/pdf/1707.05005.pdf">https://arxiv.org/pdf/1707.05005.pdf</a></p>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p>weisfeiler_lehman_graph_hash</p>
</div>
</dd></dl>

</section>
<section id="module-pymatgen.util.io_utils">
<span id="pymatgen-util-io-utils-module"></span><h2>pymatgen.util.io_utils module<a class="headerlink" href="#module-pymatgen.util.io_utils" title="Link to this heading"></a></h2>
<p>This module provides utility classes for io operations.</p>
<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.io_utils.clean_lines">
<span class="sig-name descname"><span class="pre">clean_lines</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">string_list</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">list</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="n"><span class="pre">remove_empty_lines</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">rstrip_only</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Iterator</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/io_utils.py#L25-L50"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.io_utils.clean_lines" title="Link to this definition"></a></dt>
<dd><p>Remove leading and trailing whitespaces from a list of strings.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>string_list</strong> (<em>list</em><em>[</em><em>str</em><em>]</em>) – List of strings.</p></li>
<li><p><strong>remove_empty_lines</strong> (<em>bool</em>) – Set to True to skip lines which are empty after
stripping.</p></li>
<li><p><strong>rstrip_only</strong> (<em>bool</em>) – Set to True to strip trailing whitespaces only (i.e.,
to retain leading whitespaces). Defaults to False.</p></li>
</ul>
</dd>
<dt class="field-even">Yields<span class="colon">:</span></dt>
<dd class="field-even"><p><em>str</em> – clean string with no leading and trailing whitespaces.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.io_utils.micro_pyawk">
<span class="sig-name descname"><span class="pre">micro_pyawk</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">Path</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">search</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">list</span><span class="p"><span class="pre">[</span></span><span class="pre">tuple</span><span class="p"><span class="pre">[</span></span><span class="pre">re.Pattern</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Callable</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Callable</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="n"><span class="pre">results</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">debug</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Callable</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">postdebug</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Callable</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Any</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/io_utils.py#L53-L111"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.io_utils.micro_pyawk" title="Link to this definition"></a></dt>
<dd><p>Small awk-mimicking search routine.</p>
<p>This function goes through each line in the file, and if <cite>regex</cite> matches that
line AND test(results, line) is True (OR test is None) we execute
run(results, match), where match is the Match object from running
Pattern.match.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>filename</strong> (<em>PathLike</em>) – The file to search through.</p></li>
<li><p><strong>search</strong> (<em>list</em><em>[</em><em>tuple</em><em>[</em><em>Pattern</em><em> | </em><em>str</em><em>, </em><em>Callable</em><em>, </em><em>Callable</em><em>]</em><em>]</em>) – The “search program” of
3 elements, i.e. [(regex, test, run), …].
Here <cite>regex</cite> is either a Pattern object, or a string that we compile
into a Pattern.</p></li>
<li><p><strong>results</strong> – An object to store results. Default as an empty dictionary.
Passing a results object let you interact with it via <cite>run</cite> and <cite>test</cite>.
Hence, in many occasions it is clever to use the instance itself as results.</p></li>
<li><p><strong>debug</strong> (<em>Callable</em>) – Debug <cite>run</cite>.</p></li>
<li><p><strong>postdebug</strong> (<em>Callable</em>) – Post debug <cite>run</cite> after debug <cite>run</cite>.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>The updated <cite>results</cite> object.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>Any</p>
</dd>
</dl>
<p>Author: Rickard Armiento, Ioannis Petousis</p>
</dd></dl>

</section>
<section id="module-pymatgen.util.joblib">
<span id="pymatgen-util-joblib-module"></span><h2>pymatgen.util.joblib module<a class="headerlink" href="#module-pymatgen.util.joblib" title="Link to this heading"></a></h2>
<p>This module provides utility functions for getting progress bar with joblib.</p>
<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.joblib.set_python_warnings">
<span class="sig-name descname"><span class="pre">set_python_warnings</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">warnings</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../../../../../.local/share/uv/python/cpython-3.11.11-macos-aarch64-none/lib/python3.11/contextlib.py#L38-L51"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.joblib.set_python_warnings" title="Link to this definition"></a></dt>
<dd><p>Context manager to set the PYTHONWARNINGS environment variable to the
given value. This is useful for preventing spam when using parallel processing.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.joblib.tqdm_joblib">
<span class="sig-name descname"><span class="pre">tqdm_joblib</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tqdm_object</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">tqdm</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Iterator</span><span class="p"><span class="pre">[</span></span><span class="pre">None</span><span class="p"><span class="pre">]</span></span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../../../../../.local/share/uv/python/cpython-3.11.11-macos-aarch64-none/lib/python3.11/contextlib.py#L17-L35"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.joblib.tqdm_joblib" title="Link to this definition"></a></dt>
<dd><p>Context manager to patch joblib to report into tqdm progress bar given
as argument.</p>
</dd></dl>

</section>
<section id="module-pymatgen.util.misc">
<span id="pymatgen-util-misc-module"></span><h2>pymatgen.util.misc module<a class="headerlink" href="#module-pymatgen.util.misc" title="Link to this heading"></a></h2>
<p>Other util functions.</p>
<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.misc.is_np_dict_equal">
<span class="sig-name descname"><span class="pre">is_np_dict_equal</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dict1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dict2</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">bool</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/misc.py#L8-L21"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.misc.is_np_dict_equal" title="Link to this definition"></a></dt>
<dd><p>Compare two dict whose value could be NumPy arrays.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>dict1</strong> (<em>dict</em>) – The first dict.</p></li>
<li><p><strong>dict2</strong> (<em>dict</em>) – The second dict.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Whether these two dicts are equal.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>bool</p>
</dd>
</dl>
</dd></dl>

</section>
<section id="module-pymatgen.util.num">
<span id="pymatgen-util-num-module"></span><h2>pymatgen.util.num module<a class="headerlink" href="#module-pymatgen.util.num" title="Link to this heading"></a></h2>
<p>This module provides utilities for basic math operations.</p>
<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.num.make_symmetric_matrix_from_upper_tri">
<span class="sig-name descname"><span class="pre">make_symmetric_matrix_from_upper_tri</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">val</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ArrayLike</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">NDArray</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/num.py#L33-L59"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.num.make_symmetric_matrix_from_upper_tri" title="Link to this definition"></a></dt>
<dd><dl class="simple">
<dt>Construct a 3x3 symmetric matrix from its upper triangular</dt><dd><p>elements in flat array form:
[A_xx, A_yy, A_zz, A_xy, A_xz, A_yz].</p>
</dd>
<dt>To the full symmetric matrix:</dt><dd><dl class="simple">
<dt>[[A_xx, A_xy, A_xz],</dt><dd><p>[A_xy, A_yy, A_yz],
[A_xz, A_yz, A_zz]]</p>
</dd>
</dl>
</dd>
</dl>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>val</strong> (<em>ArrayLike</em>) – Flattened upper triangular elements.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>The symmetric matrix.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>NDArray</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.num.round_to_sigfigs">
<span class="sig-name descname"><span class="pre">round_to_sigfigs</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">num</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">sig_figs</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">int</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">float</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/num.py#L13-L30"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.num.round_to_sigfigs" title="Link to this definition"></a></dt>
<dd><p>Rounds a number to a specific number of significant
figures instead of to a specific precision.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>rounded number.</p>
</dd>
<dt class="field-even">Return type<span class="colon">:</span></dt>
<dd class="field-even"><p>float</p>
</dd>
</dl>
</dd></dl>

</section>
<section id="module-pymatgen.util.numba">
<span id="pymatgen-util-numba-module"></span><h2>pymatgen.util.numba module<a class="headerlink" href="#module-pymatgen.util.numba" title="Link to this heading"></a></h2>
<p>This module provides a wrapper for numba such that no functionality
is lost if numba is not available. Numba is a just-in-time compiler
that can significantly accelerate the evaluation of certain functions
if installed.</p>
<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.numba.jit">
<span class="sig-name descname"><span class="pre">jit</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">func</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/numba.py#L17-L19"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.numba.jit" title="Link to this definition"></a></dt>
<dd><p>Replacement for numba.jit when numba is not installed that does nothing.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.numba.njit">
<span class="sig-name descname"><span class="pre">njit</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">func</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/numba.py#L13-L15"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.numba.njit" title="Link to this definition"></a></dt>
<dd><p>Replacement for numba.njit when numba is not installed that does nothing.</p>
</dd></dl>

</section>
<section id="module-pymatgen.util.plotting">
<span id="pymatgen-util-plotting-module"></span><h2>pymatgen.util.plotting module<a class="headerlink" href="#module-pymatgen.util.plotting" title="Link to this heading"></a></h2>
<p>Utilities for generating nicer plots.</p>
<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.plotting.add_fig_kwargs">
<span class="sig-name descname"><span class="pre">add_fig_kwargs</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">func</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/plotting.py#L703-L794"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.plotting.add_fig_kwargs" title="Link to this definition"></a></dt>
<dd><p>Decorator that adds keyword arguments for functions returning matplotlib
figures.</p>
<p>The function should return either a matplotlib figure or None to signal
some sort of error/unexpected event.
See doc string below for the list of supported options.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.plotting.format_formula">
<span class="sig-name descname"><span class="pre">format_formula</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">formula</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">str</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/plotting.py#L454-L478"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.plotting.format_formula" title="Link to this definition"></a></dt>
<dd><p>Convert str of chemical formula into
latex format for labelling purposes.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>formula</strong> (<em>str</em>) – Chemical formula</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.plotting.get_ax3d_fig">
<span class="sig-name descname"><span class="pre">get_ax3d_fig</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">ax</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Axes</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">tuple</span><span class="p"><span class="pre">[</span></span><span class="pre">Axes3D</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Figure</span><span class="p"><span class="pre">]</span></span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/plotting.py#L638-L656"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.plotting.get_ax3d_fig" title="Link to this definition"></a></dt>
<dd><p>Helper function used in plot functions supporting an optional Axes3D
argument. If ax is None, we build the <cite>matplotlib</cite> figure and create the
Axes3D else we return the current active figure.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>ax</strong> (<em>Axes3D</em><em>, </em><em>optional</em>) – Axes3D object. Defaults to None.</p></li>
<li><p><strong>kwargs</strong> – keyword arguments are passed to plt.figure if ax is not None.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>matplotlib Axes3D and corresponding figure objects</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>tuple[Axes3D, Figure]</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.plotting.get_ax_fig">
<span class="sig-name descname"><span class="pre">get_ax_fig</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">ax</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Axes</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">tuple</span><span class="p"><span class="pre">[</span></span><span class="pre">Axes</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Figure</span><span class="p"><span class="pre">]</span></span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/plotting.py#L617-L635"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.plotting.get_ax_fig" title="Link to this definition"></a></dt>
<dd><p>Helper function used in plot functions supporting an optional Axes argument.
If ax is None, we build the <cite>matplotlib</cite> figure and create the Axes else
we return the current active figure.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>ax</strong> (<em>Axes</em><em>, </em><em>optional</em>) – Axes object. Defaults to None.</p></li>
<li><p><strong>kwargs</strong> – keyword arguments are passed to plt.figure if ax is not None.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>matplotlib Axes object and Figure objects</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>tuple[Axes, Figure]</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.plotting.get_axarray_fig_plt">
<span class="sig-name descname"><span class="pre">get_axarray_fig_plt</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">ax_array</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">nrows</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ncols</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">sharex</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">sharey</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">squeeze</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">subplot_kw</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">gridspec_kw</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">fig_kw</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/plotting.py#L659-L700"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.plotting.get_axarray_fig_plt" title="Link to this definition"></a></dt>
<dd><p>Helper function used in plot functions that accept an optional array of Axes
as argument. If ax_array is None, we build the <cite>matplotlib</cite> figure and
create the array of Axes by calling plt.subplots else we return the
current active figure.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>Array of Axes objects
figure: matplotlib figure
plt: matplotlib pyplot module.</p>
</dd>
<dt class="field-even">Return type<span class="colon">:</span></dt>
<dd class="field-even"><p>ax</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.plotting.periodic_table_heatmap">
<span class="sig-name descname"><span class="pre">periodic_table_heatmap</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">elemental_data</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">cbar_label</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">cbar_label_size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">14</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">show_plot</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">cmap</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'YlOrRd'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">cmap_range</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">blank_color</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'grey'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">edge_color</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'white'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value_format</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">value_fontsize</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">10</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">symbol_fontsize</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">14</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">max_row</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">int</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">9</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">readable_fontcolor</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pymatviz</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/plotting.py#L210-L451"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.plotting.periodic_table_heatmap" title="Link to this definition"></a></dt>
<dd><p>A static method that generates a heat map overlaid on a periodic table.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>elemental_data</strong> (<em>dict</em>) – A dictionary with the element as a key and a
value assigned to it, e.g. surface energy and frequency, etc.
Elements missing in the elemental_data will be grey by default
in the final table elemental_data={“Fe”: 4.2, “O”: 5.0}.</p></li>
<li><p><strong>cbar_label</strong> (<em>str</em>) – Label of the color bar. Default is “”.</p></li>
<li><p><strong>cbar_label_size</strong> (<em>float</em>) – Font size for the color bar label. Default is 14.</p></li>
<li><p><strong>cmap_range</strong> (<em>tuple</em>) – Minimum and maximum value of the color map scale.
If None, the color map will automatically scale to the range of the
data.</p></li>
<li><p><strong>show_plot</strong> (<em>bool</em>) – Whether to show the heatmap. Default is False.</p></li>
<li><p><strong>value_format</strong> (<em>str</em>) – Formatting string to show values. If None, no value
is shown. Example: “%.4f” shows float to four decimals.</p></li>
<li><p><strong>value_fontsize</strong> (<em>float</em>) – Font size for values. Default is 10.</p></li>
<li><p><strong>symbol_fontsize</strong> (<em>float</em>) – Font size for element symbols. Default is 14.</p></li>
<li><p><strong>cmap</strong> (<em>str</em>) – Color scheme of the heatmap. Default is ‘YlOrRd’.
Refer to the matplotlib documentation for other options.</p></li>
<li><p><strong>blank_color</strong> (<em>str</em>) – Color assigned for the missing elements in
elemental_data. Default is “grey”.</p></li>
<li><p><strong>edge_color</strong> (<em>str</em>) – Color assigned for the edge of elements in the
periodic table. Default is “white”.</p></li>
<li><p><strong>max_row</strong> (<em>int</em>) – Maximum number of rows of the periodic table to be
shown. Default is 9, which means the periodic table heat map covers
the standard 7 rows of the periodic table + 2 rows for the lanthanides
and actinides. Use a value of max_row = 7 to exclude the lanthanides and
actinides.</p></li>
<li><p><strong>readable_fontcolor</strong> (<em>bool</em>) – Whether to use readable font color depending
on background color. Default is False.</p></li>
<li><p><strong>pymatviz</strong> (<em>bool</em>) – Whether to use pymatviz to generate the heatmap. Defaults to True.
See <a class="reference external" href="https://github.com/janosh/pymatviz">https://github.com/janosh/pymatviz</a>.</p></li>
<li><p><strong>kwargs</strong> – Passed to pymatviz.ptable_heatmap_plotly</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>matplotlib Axes object</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>plt.Axes</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.plotting.pretty_plot">
<span class="sig-name descname"><span class="pre">pretty_plot</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">width</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">8</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">height</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ax</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Axes</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dpi</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">color_cycle</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">tuple</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">str</span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">('qualitative',</span> <span class="pre">'Set1_9')</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Axes</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/plotting.py#L32-L81"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.plotting.pretty_plot" title="Link to this definition"></a></dt>
<dd><p>Get a publication quality plot, with nice defaults for font sizes etc.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>width</strong> (<em>float</em>) – Width of plot in inches. Defaults to 8in.</p></li>
<li><p><strong>height</strong> (<em>float</em>) – Height of plot in inches. Defaults to width * golden
ratio.</p></li>
<li><p><strong>ax</strong> (<em>Axes</em>) – If ax is supplied, changes will be made to an
existing plot. Otherwise, a new plot will be created.</p></li>
<li><p><strong>dpi</strong> (<em>float</em>) – Sets dot per inch for figure. Defaults to 300.</p></li>
<li><p><strong>color_cycle</strong> (<em>tuple</em>) – Set the color cycle for new plots to one of the
color sets in palettable. Defaults to a qualitative Set1_9.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>matplotlib axes object with properly sized fonts.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>Axes</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.plotting.pretty_plot_two_axis">
<span class="sig-name descname"><span class="pre">pretty_plot_two_axis</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">x</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">y1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">y2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">xlabel</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">y1label</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">y2label</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">width</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">8</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">height</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dpi</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">300</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">plot_kwargs</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/plotting.py#L84-L174"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.plotting.pretty_plot_two_axis" title="Link to this definition"></a></dt>
<dd><p>Variant of pretty_plot that does a dual axis plot. Adapted from matplotlib
examples. Makes it easier to create plots with different axes.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>x</strong> (<em>Sequence</em><em>[</em><em>float</em><em>]</em>) – Data for x-axis.</p></li>
<li><p><strong>y1</strong> (<em>Sequence</em><em>[</em><em>float</em><em>] </em><em>| </em><em>dict</em><em>[</em><em>str</em><em>, </em><em>Sequence</em><em>[</em><em>float</em><em>]</em><em>]</em>) – Data for y1 axis (left). If a dict, it will
be interpreted as a {label: sequence}.</p></li>
<li><p><strong>y2</strong> (<em>Sequence</em><em>[</em><em>float</em><em>] </em><em>| </em><em>dict</em><em>[</em><em>str</em><em>, </em><em>Sequence</em><em>[</em><em>float</em><em>]</em><em>]</em>) – Data for y2 axis (right). If a dict, it will
be interpreted as a {label: sequence}.</p></li>
<li><p><strong>xlabel</strong> (<em>str</em>) – If not None, this will be the label for the x-axis.</p></li>
<li><p><strong>y1label</strong> (<em>str</em>) – If not None, this will be the label for the y1-axis.</p></li>
<li><p><strong>y2label</strong> (<em>str</em>) – If not None, this will be the label for the y2-axis.</p></li>
<li><p><strong>width</strong> (<em>float</em>) – Width of plot in inches. Defaults to 8in.</p></li>
<li><p><strong>height</strong> (<em>float</em>) – Height of plot in inches. Defaults to width * golden
ratio.</p></li>
<li><p><strong>dpi</strong> (<em>int</em>) – Sets dot per inch for figure. Defaults to 300.</p></li>
<li><p><strong>plot_kwargs</strong> – Passthrough kwargs to matplotlib’s plot method. e.g.
linewidth, etc.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>matplotlib axes object with properly sized fonts.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>plt.Axes</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.plotting.pretty_polyfit_plot">
<span class="sig-name descname"><span class="pre">pretty_polyfit_plot</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">x</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">NDArray</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">y</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">NDArray</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">deg</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">int</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">xlabel</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ylabel</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kwargs</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/plotting.py#L177-L199"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.plotting.pretty_polyfit_plot" title="Link to this definition"></a></dt>
<dd><p>Convenience method to plot data with trend lines based on polynomial fit.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>x</strong> – Sequence of x data.</p></li>
<li><p><strong>y</strong> – Sequence of y data.</p></li>
<li><p><strong>deg</strong> (<em>int</em>) – Degree of polynomial. Defaults to 1.</p></li>
<li><p><strong>xlabel</strong> (<em>str</em>) – Label for x-axis.</p></li>
<li><p><strong>ylabel</strong> (<em>str</em>) – Label for y-axis.</p></li>
<li><p><strong>kwargs</strong> – Keyword args passed to pretty_plot.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>plt.Axes</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.plotting.van_arkel_triangle">
<span class="sig-name descname"><span class="pre">van_arkel_triangle</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">list_of_materials</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Sequence</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">annotate</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/plotting.py#L481-L614"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.plotting.van_arkel_triangle" title="Link to this definition"></a></dt>
<dd><p>A static method that generates a binary van Arkel-Ketelaar triangle to
quantify the ionic, metallic and covalent character of a compound
by plotting the electronegativity difference (y) vs average (x).
See:</p>
<blockquote>
<div><dl class="simple">
<dt>A.E. van Arkel, Molecules and Crystals in Inorganic Chemistry,</dt><dd><p>Interscience, New York (1956)</p>
</dd>
</dl>
</div></blockquote>
<dl class="simple">
<dt>and</dt><dd><dl class="simple">
<dt>J.A.A Ketelaar, Chemical Constitution (2nd edition), An Introduction</dt><dd><p>to the Theory of the Chemical Bond, Elsevier, New York (1958).</p>
</dd>
</dl>
</dd>
</dl>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>list_of_materials</strong> (<em>list</em>) – A list of computed entries of binary
materials or a list of lists containing two elements (str).</p></li>
<li><p><strong>annotate</strong> (<em>bool</em>) – Whether or not to label the points on the
triangle with reduced formula (if list of entries) or pair
of elements (if list of list of str).</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>matplotlib Axes object</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>plt.Axes</p>
</dd>
</dl>
</dd></dl>

</section>
<section id="module-pymatgen.util.provenance">
<span id="pymatgen-util-provenance-module"></span><h2>pymatgen.util.provenance module<a class="headerlink" href="#module-pymatgen.util.provenance" title="Link to this heading"></a></h2>
<p>Classes and methods related to the Structure Notation Language (SNL).</p>
<dl class="py class">
<dt class="sig sig-object py" id="pymatgen.util.provenance.Author">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">Author</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">email</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/provenance.py#L103-L160"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.provenance.Author" title="Link to this definition"></a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">NamedTuple</span></code></p>
<p>An Author contains two fields: name and email. It is meant to represent
the author of a Structure or the author of a code that was applied to a Structure.</p>
<p>Create new instance of Author(name, email)</p>
<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.provenance.Author.as_dict">
<span class="sig-name descname"><span class="pre">as_dict</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">dict</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">str</span><span class="p"><span class="pre">]</span></span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/provenance.py#L115-L117"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.provenance.Author.as_dict" title="Link to this definition"></a></dt>
<dd><p>Get MSONable dict.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="pymatgen.util.provenance.Author.email">
<span class="sig-name descname"><span class="pre">email</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">str</span></em><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/util/provenance.py"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.provenance.Author.email" title="Link to this definition"></a></dt>
<dd><p>Alias for field number 1</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.provenance.Author.from_dict">
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">from_dict</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dct</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">dict</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">str</span><span class="p"><span class="pre">]</span></span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Self</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/provenance.py#L119-L128"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.provenance.Author.from_dict" title="Link to this definition"></a></dt>
<dd><dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>dct</strong> (<em>dict</em>) – Dict representation.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Author</p>
</dd>
</dl>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="pymatgen.util.provenance.Author.name">
<span class="sig-name descname"><span class="pre">name</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">str</span></em><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/util/provenance.py"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.provenance.Author.name" title="Link to this definition"></a></dt>
<dd><p>Alias for field number 0</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.provenance.Author.parse_author">
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">parse_author</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">author</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">dict</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">str</span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">tuple</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">str</span><span class="p"><span class="pre">]</span></span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Self</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/provenance.py#L130-L160"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.provenance.Author.parse_author" title="Link to this definition"></a></dt>
<dd><p>Parse an Author object from either a String, dict, or tuple.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>author</strong> – in one of the three accepted formats:
- A string formatted as “NAME &lt;<a class="reference external" href="mailto:email&#37;&#52;&#48;domain&#46;com">email<span>&#64;</span>domain<span>&#46;</span>com</a>&gt;”.
- A (name, email) tuple.
- A dict with name and email as keys.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>An Author object.</p>
</dd>
</dl>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="pymatgen.util.provenance.HistoryNode">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">HistoryNode</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">url</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">description</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/provenance.py#L51-L100"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.provenance.HistoryNode" title="Link to this definition"></a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">NamedTuple</span></code></p>
<p>A HistoryNode represents a step in the chain of events that lead to a
Structure. HistoryNodes leave ‘breadcrumbs’ so that you can trace back how
a Structure was created. For example, a HistoryNode might represent pulling
a Structure from an external database such as the ICSD or CSD. Or, it might
represent the application of a code (e.g. pymatgen) to the Structure, with
a custom description of how that code was applied (e.g. a site removal
Transformation was applied).</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="pymatgen.util.provenance.HistoryNode.name">
<span class="sig-name descname"><span class="pre">name</span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/util/provenance.py"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.provenance.HistoryNode.name" title="Link to this definition"></a></dt>
<dd><p>The name of a code or resource that this Structure encountered in its history.</p>
<dl class="field-list simple">
<dt class="field-odd">Type<span class="colon">:</span></dt>
<dd class="field-odd"><p>str</p>
</dd>
</dl>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="pymatgen.util.provenance.HistoryNode.url">
<span class="sig-name descname"><span class="pre">url</span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/util/provenance.py"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.provenance.HistoryNode.url" title="Link to this definition"></a></dt>
<dd><p>The URL of that code/resource.</p>
<dl class="field-list simple">
<dt class="field-odd">Type<span class="colon">:</span></dt>
<dd class="field-odd"><p>str</p>
</dd>
</dl>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="pymatgen.util.provenance.HistoryNode.description">
<span class="sig-name descname"><span class="pre">description</span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/util/provenance.py"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.provenance.HistoryNode.description" title="Link to this definition"></a></dt>
<dd><p>A free-form description of how the code/resource is related to the Structure.</p>
<dl class="field-list simple">
<dt class="field-odd">Type<span class="colon">:</span></dt>
<dd class="field-odd"><p>str</p>
</dd>
</dl>
</dd></dl>

<p>Create new instance of HistoryNode(name, url, description)</p>
<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.provenance.HistoryNode.as_dict">
<span class="sig-name descname"><span class="pre">as_dict</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">dict</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">str</span><span class="p"><span class="pre">]</span></span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/provenance.py#L70-L72"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.provenance.HistoryNode.as_dict" title="Link to this definition"></a></dt>
<dd><p>Get MSONable dict.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="id0">
<span class="sig-name descname"><span class="pre">description</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">str</span></em><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/util/provenance.py"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#id0" title="Link to this definition"></a></dt>
<dd><p>Alias for field number 2</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.provenance.HistoryNode.from_dict">
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">from_dict</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dct</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">dict</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">str</span><span class="p"><span class="pre">]</span></span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Self</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/provenance.py#L74-L83"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.provenance.HistoryNode.from_dict" title="Link to this definition"></a></dt>
<dd><dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>dct</strong> (<em>dict</em>) – Dict representation.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>HistoryNode</p>
</dd>
</dl>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="id7">
<span class="sig-name descname"><span class="pre">name</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">str</span></em><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/util/provenance.py"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#id7" title="Link to this definition"></a></dt>
<dd><p>Alias for field number 0</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.provenance.HistoryNode.parse_history_node">
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">parse_history_node</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">h_node</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Self</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/provenance.py#L85-L100"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.provenance.HistoryNode.parse_history_node" title="Link to this definition"></a></dt>
<dd><p>Parse a History Node object from either a dict or a tuple.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>h_node</strong> – A dict with name/url/description fields or a 3-element tuple.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>HistoryNode</p>
</dd>
</dl>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="id8">
<span class="sig-name descname"><span class="pre">url</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">str</span></em><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/util/provenance.py"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#id8" title="Link to this definition"></a></dt>
<dd><p>Alias for field number 1</p>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="pymatgen.util.provenance.StructureNL">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">StructureNL</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">struct_or_mol</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="pymatgen.core.html#pymatgen.core.structure.Structure" title="pymatgen.core.structure.Structure"><span class="pre">Structure</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference internal" href="pymatgen.core.html#pymatgen.core.structure.Molecule" title="pymatgen.core.structure.Molecule"><span class="pre">Molecule</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">authors</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">list</span><span class="p"><span class="pre">[</span></span><span class="pre">dict</span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">list</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="n"><span class="pre">projects</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">list</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">references</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">remarks</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">list</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">dict</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">history</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">list</span><span class="p"><span class="pre">[</span></span><span class="pre">dict</span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">created_at</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">datetime</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/provenance.py#L163-L395"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.provenance.StructureNL" title="Link to this definition"></a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></p>
<p>The Structure Notation Language (SNL, pronounced “snail”) is a container for a pymatgen
Structure/Molecule object with some additional fields for enhanced provenance.</p>
<dl class="simple">
<dt>It is meant to be imported/exported in a JSON file format with the following structure:</dt><dd><ul class="simple">
<li><p>sites</p></li>
<li><p>lattice (optional)</p></li>
<li><dl class="simple">
<dt>about</dt><dd><ul>
<li><p>created_at</p></li>
<li><p>authors</p></li>
<li><p>projects</p></li>
<li><p>references</p></li>
<li><p>remarks</p></li>
<li><p>data</p></li>
<li><p>history</p></li>
</ul>
</dd>
</dl>
</li>
</ul>
</dd>
</dl>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>struct_or_mol</strong> – A pymatgen Structure/Molecule object</p></li>
<li><p><strong>authors</strong> (<em>list</em><em> | </em><em>str</em>) – <ul>
<li><p>List of {“name”:””, “email”:””} dicts.</p></li>
<li><p>List of strings as “John Doe &lt;<a class="reference external" href="mailto:johndoe&#37;&#52;&#48;gmail&#46;com">johndoe<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt;”.</p></li>
<li><p>A single String with commas separating authors.</p></li>
</ul>
</p></li>
<li><p><strong>projects</strong> (<em>list</em><em>[</em><em>str</em><em>] </em><em>| </em><em>str</em>) – e.g. [“Project A”, “Project B”]</p></li>
<li><p><strong>references</strong> (<em>str</em>) – A string in BibTeX format</p></li>
<li><p><strong>remarks</strong> (<em>list</em><em>[</em><em>str</em><em>]</em>) – e.g. [“Remark A”, “Remark B”]</p></li>
<li><p><strong>data</strong> (<em>dict</em>) – A free form dict. Namespaced at the root level with an
underscore, e.g. {“_materialsproject”: &lt;custom data&gt;}</p></li>
<li><p><strong>history</strong> (<em>list</em><em>[</em><em>dict</em><em>]</em>) – e.g. [{“name”:””, “url”:””, “description”:{}}]</p></li>
<li><p><strong>created_at</strong> (<em>datetime</em>) – Creation date.</p></li>
</ul>
</dd>
</dl>
<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.provenance.StructureNL.as_dict">
<span class="sig-name descname"><span class="pre">as_dict</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">dict</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Any</span><span class="p"><span class="pre">]</span></span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/provenance.py#L300-L314"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.provenance.StructureNL.as_dict" title="Link to this definition"></a></dt>
<dd><p>Get MSONable dict.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.provenance.StructureNL.from_dict">
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">from_dict</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dct</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">dict</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">Any</span><span class="p"><span class="pre">]</span></span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">Self</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/provenance.py#L316-L341"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.provenance.StructureNL.from_dict" title="Link to this definition"></a></dt>
<dd><dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>dct</strong> (<em>dict</em>) – Dict representation.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Class</p>
</dd>
</dl>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.provenance.StructureNL.from_structures">
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">from_structures</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">structures</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Sequence</span><span class="p"><span class="pre">[</span></span><a class="reference internal" href="pymatgen.core.html#pymatgen.core.structure.Structure" title="pymatgen.core.structure.Structure"><span class="pre">Structure</span></a><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="n"><span class="pre">authors</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">projects</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">list</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">references</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">remarks</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">list</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">list</span><span class="p"><span class="pre">[</span></span><span class="pre">dict</span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">histories</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">list</span><span class="p"><span class="pre">[</span></span><span class="pre">list</span><span class="p"><span class="pre">[</span></span><span class="pre">dict</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">created_at</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">datetime</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">list</span><span class="p"><span class="pre">[</span></span><span class="pre">Self</span><span class="p"><span class="pre">]</span></span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/provenance.py#L343-L395"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.provenance.StructureNL.from_structures" title="Link to this definition"></a></dt>
<dd><p>A convenience method for getting a list of StructureNL objects by
specifying structures and metadata separately. Some of the metadata
is applied to all of the structures for ease of use.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>structures</strong> (<em>Sequence</em><em>[</em><a class="reference internal" href="pymatgen.core.html#pymatgen.core.structure.Structure" title="pymatgen.core.structure.Structure"><em>Structure</em></a><em>]</em>) – Structure objects</p></li>
<li><p><strong>authors</strong> – <em>List</em> of {“name”:’’, “email”:’’} dicts,
<em>list</em> of Strings as ‘John Doe &lt;<a class="reference external" href="mailto:johndoe&#37;&#52;&#48;gmail&#46;com">johndoe<span>&#64;</span>gmail<span>&#46;</span>com</a>&gt;’,
or a single String with commas separating authors</p></li>
<li><p><strong>projects</strong> (<em>list</em><em>[</em><em>str</em><em>]</em>) – e.g. [“Project A”, “Project B”]. This
applies to all structures.</p></li>
<li><p><strong>references</strong> (<em>str</em>) – A String in BibTeX format. This applies to all
structures.</p></li>
<li><p><strong>remarks</strong> (<em>list</em><em>[</em><em>str</em><em>]</em>) – e.g. [“Remark A”, “Remark B”].</p></li>
<li><p><strong>data</strong> (<em>list</em><em>[</em><em>dict</em><em>]</em>) – Free form dicts. Namespaced at the root level
with an underscore, e.g. {“_materialsproject”:&lt;custom data&gt;}
. The length of data should be the same as the list of
structures if not None.</p></li>
<li><p><strong>histories</strong> (<em>list</em><em>[</em><em>list</em><em>[</em><em>dict</em><em>]</em><em>]</em>) – e.g. [[{“name”:””, “url”:””,
“description”:{}}], …] The length of histories should be the
same as the list of structures if not None.</p></li>
<li><p><strong>created_at</strong> (<em>datetime</em>) – Creation date.</p></li>
</ul>
</dd>
</dl>
</dd></dl>

</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.provenance.is_valid_bibtex">
<span class="sig-name descname"><span class="pre">is_valid_bibtex</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">reference</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">bool</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/provenance.py#L32-L48"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.provenance.is_valid_bibtex" title="Link to this definition"></a></dt>
<dd><p>Validate that a reference is in proper BibTeX format.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>reference</strong> (<em>str</em>) – Reference in BibTeX format.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>True if reference is valid BibTeX.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>bool</p>
</dd>
</dl>
</dd></dl>

</section>
<section id="module-pymatgen.util.string">
<span id="pymatgen-util-string-module"></span><h2>pymatgen.util.string module<a class="headerlink" href="#module-pymatgen.util.string" title="Link to this heading"></a></h2>
<p>This module provides utility classes for string operations.</p>
<p>TODO: make standalone functions in this module use the same implementation as Stringify
Note: previous deprecations of standalone functions in this module were removed due to
a community need.</p>
<dl class="py class">
<dt class="sig sig-object py" id="pymatgen.util.string.Stringify">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">Stringify</span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/string.py#L54-L110"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.string.Stringify" title="Link to this definition"></a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></p>
<p>Mix-in class for string formatting, e.g. superscripting numbers and symbols or superscripting.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="pymatgen.util.string.Stringify.STRING_MODE">
<span class="sig-name descname"><span class="pre">STRING_MODE</span></span><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">'SUBSCRIPT'</span></em><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/util/string.py"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.string.Stringify.STRING_MODE" title="Link to this definition"></a></dt>
<dd></dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.string.Stringify.to_html_string">
<span class="sig-name descname"><span class="pre">to_html_string</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">str</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/string.py#L83-L95"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.string.Stringify.to_html_string" title="Link to this definition"></a></dt>
<dd><p>Generate a HTML formatted string. This uses the output from to_latex_string to generate a HTML output.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>HTML formatted string.</p>
</dd>
</dl>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.string.Stringify.to_latex_string">
<span class="sig-name descname"><span class="pre">to_latex_string</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">str</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/string.py#L65-L81"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.string.Stringify.to_latex_string" title="Link to this definition"></a></dt>
<dd><p>Generate a LaTeX formatted string. The mode is set by the class variable STRING_MODE, which defaults to
“SUBSCRIPT”. e.g. Fe2O3 is transformed to Fe$_{2}$O$_{3}$. Setting STRING_MODE to “SUPERSCRIPT” creates
superscript, e.g. Fe2+ becomes Fe^{2+}. The initial string is obtained from the class’s __str__ method.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns<span class="colon">:</span></dt>
<dd class="field-odd"><p>for LaTeX display with proper sub-/superscripts.</p>
</dd>
<dt class="field-even">Return type<span class="colon">:</span></dt>
<dd class="field-even"><p>str</p>
</dd>
</dl>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.string.Stringify.to_pretty_string">
<span class="sig-name descname"><span class="pre">to_pretty_string</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">str</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/string.py#L59-L63"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.string.Stringify.to_pretty_string" title="Link to this definition"></a></dt>
<dd><p>A pretty string representation. By default, the __str__ output is used, but this method can be
overridden if a different representation from default is desired.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.string.Stringify.to_unicode_string">
<span class="sig-name descname"><span class="pre">to_unicode_string</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">str</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/string.py#L97-L110"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.string.Stringify.to_unicode_string" title="Link to this definition"></a></dt>
<dd><p>Unicode string with proper sub and superscripts. Note that this works only
with systems where the sub and superscripts are pure integers.</p>
</dd></dl>

</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.string.charge_string">
<span class="sig-name descname"><span class="pre">charge_string</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">charge</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">brackets</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">explicit_one</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">str</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/string.py#L163-L182"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.string.charge_string" title="Link to this definition"></a></dt>
<dd><p>Get a string representing the charge of an Ion. By default, the
charge is placed in brackets with the sign preceding the magnitude, e.g.
‘[+2]’. For uncharged species, the string returned is ‘(aq)’.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>charge</strong> (<em>float</em>) – The charge of the ion.</p></li>
<li><p><strong>brackets</strong> (<em>bool</em>) – Whether to enclose the charge in brackets, e.g. [+2]. Default is True.</p></li>
<li><p><strong>explicit_one</strong> (<em>bool</em>) – whether to include the number one for monovalent ions,
e.g. “+1” rather than “+”. Default is True.</p></li>
</ul>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.string.disordered_formula">
<span class="sig-name descname"><span class="pre">disordered_formula</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">disordered_struct</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="pymatgen.core.html#pymatgen.core.structure.Structure" title="pymatgen.core.structure.Structure"><span class="pre">Structure</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">symbols</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Sequence</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">('x',</span> <span class="pre">'y',</span> <span class="pre">'z')</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">fmt</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Literal</span><span class="p"><span class="pre">[</span></span><span class="s"><span class="pre">'plain'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'HTML'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'LaTex'</span></span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">'plain'</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">str</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/string.py#L372-L471"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.string.disordered_formula" title="Link to this definition"></a></dt>
<dd><p>Get a formula of a form like AxB1-x (x=0.5)
for disordered structures. Will only return a
formula for disordered structures with one
kind of disordered site at present.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>disordered_struct</strong> (<a class="reference internal" href="pymatgen.core.html#pymatgen.core.structure.Structure" title="pymatgen.core.structure.Structure"><em>Structure</em></a>) – a disordered structure.</p></li>
<li><p><strong>symbols</strong> (<em>Sequence</em><em>[</em><em>str</em><em>]</em>) – Characters to use for subscripts,
by default this is (‘x’, ‘y’, ‘z’) but if you have more than three
disordered species more symbols will need to be added.</p></li>
<li><p><strong>fmt</strong> (<em>str</em>) – ‘plain’, ‘HTML’ or ‘LaTeX’,</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>a disordered formula string</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>str</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.string.formula_double_format">
<span class="sig-name descname"><span class="pre">formula_double_format</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">afloat</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ignore_ones</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tol</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">float</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">1e-08</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">float</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">Literal</span><span class="p"><span class="pre">[</span></span><span class="s"><span class="pre">''</span></span><span class="p"><span class="pre">]</span></span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/string.py#L139-L160"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.string.formula_double_format" title="Link to this definition"></a></dt>
<dd><p>Format a float for pretty formulas.
E.g. “Li1.0 Fe1.0 P1.0 O4.0” -&gt; “LiFePO4”.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>afloat</strong> (<em>float</em>) – The float to be formatted.</p></li>
<li><p><strong>ignore_ones</strong> (<em>bool</em>) – if true, floats of 1.0 are ignored.</p></li>
<li><p><strong>tol</strong> (<em>float</em>) – Absolute tolerance to round to nearest int. i.e. (2 + 1E-9) -&gt; 2.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Formatted float for formulas.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>float | “”</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.string.htmlify">
<span class="sig-name descname"><span class="pre">htmlify</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">formula</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">str</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/string.py#L206-L216"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.string.htmlify" title="Link to this definition"></a></dt>
<dd><p>Generate a HTML formatted formula, e.g. Fe2O3 is transformed to
Fe&lt;sub&gt;2&lt;/sub&gt;O&lt;/sub&gt;3&lt;/sub&gt;.</p>
<p>Note that Composition now has a to_html_string() method that may
be used instead.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>formula</strong> (<em>str</em>) – The string to format.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.string.latexify">
<span class="sig-name descname"><span class="pre">latexify</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">formula</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">bold</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">str</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/string.py#L185-L203"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.string.latexify" title="Link to this definition"></a></dt>
<dd><p>Generate a LaTeX formatted formula. e.g. Fe2O3 is transformed to
Fe$_{2}$O$_{3}$.</p>
<p>Note that Composition now has <cite>to_latex_string</cite> method that may
be used instead.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>formula</strong> (<em>str</em>) – Input formula.</p></li>
<li><p><strong>bold</strong> (<em>bool</em>) – Whether to make the subscripts bold. Defaults to False.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Formula suitable for display as in LaTeX with proper subscripts.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>str</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.string.latexify_spacegroup">
<span class="sig-name descname"><span class="pre">latexify_spacegroup</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">spacegroup_symbol</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">str</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/string.py#L238-L252"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.string.latexify_spacegroup" title="Link to this definition"></a></dt>
<dd><p>Generate a latex formatted spacegroup. e.g. P2_1/c is converted to
P2$_{1}$/c and P-1 is converted to P$\overline{1}$.</p>
<p>Note that SymmetryGroup now has a to_latex_string() method that may
be called instead.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>spacegroup_symbol</strong> (<em>str</em>) – A spacegroup symbol</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>A latex formatted spacegroup with proper subscripts and overlines.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>str</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.string.str_delimited">
<span class="sig-name descname"><span class="pre">str_delimited</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">results</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Sequence</span><span class="p"><span class="pre">[</span></span><span class="pre">Sequence</span><span class="p"><span class="pre">[</span></span><span class="pre">Any</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="n"><span class="pre">header</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Sequence</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">delimiter</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">'\t'</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">str</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/string.py#L113-L136"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.string.str_delimited" title="Link to this definition"></a></dt>
<dd><p>Given a tuple of tuples, generate a delimited string form.
&gt;&gt;&gt; results = ((“a”, “b”, “c”), (“d”, “e”, “f”), (1, 2, 3))
&gt;&gt;&gt; str_delimited(results, delimiter=”,”)
a,b,c
d,e,f
1,2,3.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>results</strong> (<em>Sequence</em><em>[</em><em>Sequence</em><em>[</em><em>Any</em><em>]</em><em>]</em>) – 2D sequence of arbitrary types.</p></li>
<li><p><strong>header</strong> (<em>Sequence</em><em>[</em><em>str</em><em>]</em>) – optional headers.</p></li>
<li><p><strong>delimiter</strong> (<em>str</em>) – Defaults to “t” for tab-delimited output.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Aligned string output in a table-like format.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>str</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.string.stream_has_colors">
<span class="sig-name descname"><span class="pre">stream_has_colors</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">stream</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">TextIO</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">bool</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/string.py#L308-L322"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.string.stream_has_colors" title="Link to this definition"></a></dt>
<dd><p>True if stream supports colors. Python cookbook, #475186.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.string.transformation_to_string">
<span class="sig-name descname"><span class="pre">transformation_to_string</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">matrix</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ArrayLike</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">translation_vec</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">ArrayLike</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">(0,</span> <span class="pre">0,</span> <span class="pre">0)</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">components</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">tuple</span><span class="p"><span class="pre">[</span></span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">str</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="pre">str</span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">('x',</span> <span class="pre">'y',</span> <span class="pre">'z')</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">c</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">''</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">delim</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">','</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">str</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/string.py#L325-L369"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.string.transformation_to_string" title="Link to this definition"></a></dt>
<dd><p>Convenience method. Given matrix returns string, e.g. x+2y+1/4.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>matrix</strong> (<em>ArrayLike</em>) – A 3x3 matrix.</p></li>
<li><p><strong>translation_vec</strong> (<em>tuple</em><em>[</em><em>float</em><em>, </em><em>float</em><em>, </em><em>float</em><em>]</em>) – The translation vector. Defaults to (0, 0, 0).</p></li>
<li><p><strong>components</strong> (<em>tuple</em><em>[</em><em>str</em><em>, </em><em>str</em><em>, </em><em>str</em><em>]</em>) – The components. Either (‘x’, ‘y’, ‘z’) or (‘a’, ‘b’, ‘c’).
Defaults to (‘x’, ‘y’, ‘z’).</p></li>
<li><p><strong>c</strong> (<em>str</em>) – An optional additional character to print (used for magmoms). Defaults to “”.</p></li>
<li><p><strong>delim</strong> (<em>str</em>) – A delimiter. Defaults to “,”.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>xyz string.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>str</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.string.unicodeify">
<span class="sig-name descname"><span class="pre">unicodeify</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">formula</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">str</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/string.py#L219-L235"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.string.unicodeify" title="Link to this definition"></a></dt>
<dd><p>Generate a formula with unicode subscripts, e.g. Fe2O3 is transformed
to Fe₂O₃. Does not support formulae with decimal points.</p>
<p>Note that Composition now has a to_unicode_string() method that may
be used instead.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>formula</strong> (<em>str</em>) – The string to format.</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.string.unicodeify_spacegroup">
<span class="sig-name descname"><span class="pre">unicodeify_spacegroup</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">spacegroup_symbol</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">str</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/string.py#L255-L283"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.string.unicodeify_spacegroup" title="Link to this definition"></a></dt>
<dd><p>Generate a unicode formatted spacegroup. e.g. P2$_{1}$/c is converted to
P2₁/c and P$\overline{1}$ is converted to P̅1.</p>
<p>Note that SymmetryGroup now has a to_unicode_string() method that
may be called instead.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>spacegroup_symbol</strong> (<em>str</em>) – A spacegroup symbol as LaTeX.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>A unicode spacegroup with proper subscripts and overlines.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>str</p>
</dd>
</dl>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="pymatgen.util.string.unicodeify_species">
<span class="sig-name descname"><span class="pre">unicodeify_species</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">specie_string</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">str</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/string.py#L286-L305"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.string.unicodeify_species" title="Link to this definition"></a></dt>
<dd><p>Generate a unicode formatted species string, with appropriate
superscripts for oxidation states.</p>
<p>Note that Species now has <cite>to_unicode_string</cite> method that
may be used instead.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>specie_string</strong> (<em>str</em>) – Species string, e.g. “O2-”</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Species string, e.g. “O²⁻”</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>str</p>
</dd>
</dl>
</dd></dl>

</section>
<section id="module-pymatgen.util.testing">
<span id="pymatgen-util-testing-module"></span><h2>pymatgen.util.testing module<a class="headerlink" href="#module-pymatgen.util.testing" title="Link to this heading"></a></h2>
<p>This module implements testing utilities for materials science codes.</p>
<p>While the primary use is within pymatgen, the functionality is meant to be useful for external materials science
codes as well. For instance, obtaining example crystal structures to perform tests, specialized assert methods for
materials science, etc.</p>
<dl class="py class">
<dt class="sig sig-object py" id="pymatgen.util.testing.MatSciTest">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">MatSciTest</span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/testing.py#L45-L209"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.testing.MatSciTest" title="Link to this definition"></a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">object</span></code></p>
<p><cite>pytest</cite> based test framework extended to facilitate testing with
the following methods:
- tmp_path (attribute): Temporary directory.
- get_structure: Load a Structure from <cite>util.structures</cite> with its name.
- assert_str_content_equal: Check if two strings are equal (ignore whitespaces).
- serialize_with_pickle: Test whether object(s) can be (de)serialized with pickle.
- assert_msonable: Test if obj is MSONable and return its serialized string.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="pymatgen.util.testing.MatSciTest.TEST_STRUCTURES">
<span class="sig-name descname"><span class="pre">TEST_STRUCTURES</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">ClassVar</span><span class="p"><span class="pre">[</span></span><span class="pre">dict</span><span class="p"><span class="pre">[</span></span><span class="pre">PathLike</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><a class="reference internal" href="pymatgen.core.html#pymatgen.core.structure.Structure" title="pymatgen.core.structure.Structure"><span class="pre">Structure</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">]</span></span></em><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">{PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/BaNiO3.json'):</span> <span class="pre">None,</span> <span class="pre">PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/CsCl.json'):</span> <span class="pre">None,</span> <span class="pre">PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/Graphite.json'):</span> <span class="pre">None,</span> <span class="pre">PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/He_BCC.json'):</span> <span class="pre">None,</span> <span class="pre">PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/K2O2.json'):</span> <span class="pre">None,</span> <span class="pre">PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/La2CoO4F.json'):</span> <span class="pre">None,</span> <span class="pre">PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/Li10GeP2S12.json'):</span> <span class="pre">None,</span> <span class="pre">PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/Li2O.json'):</span> <span class="pre">None,</span> <span class="pre">PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/Li2O2.json'):</span> <span class="pre">None,</span> <span class="pre">PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/Li3V2(PO4)3.json'):</span> <span class="pre">None,</span> <span class="pre">PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/LiFePO4.json'):</span> <span class="pre">None,</span> <span class="pre">PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/NaFePO4.json'):</span> <span class="pre">None,</span> <span class="pre">PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/Pb2TiZrO6.json'):</span> <span class="pre">None,</span> <span class="pre">PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/Si.json'):</span> <span class="pre">None,</span> <span class="pre">PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/SiO2.json'):</span> <span class="pre">None,</span> <span class="pre">PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/Si_SiO2_Interface.json'):</span> <span class="pre">None,</span> <span class="pre">PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/Sn.json'):</span> <span class="pre">None,</span> <span class="pre">PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/SrTiO3.json'):</span> <span class="pre">None,</span> <span class="pre">PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/TiO2.json'):</span> <span class="pre">None,</span> <span class="pre">PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/TlBiSe2.json'):</span> <span class="pre">None,</span> <span class="pre">PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/VO2.json'):</span> <span class="pre">None}</span></em><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/util/testing.py"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.testing.MatSciTest.TEST_STRUCTURES" title="Link to this definition"></a></dt>
<dd></dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.testing.MatSciTest.assert_msonable">
<em class="property"><span class="k"><span class="pre">static</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">assert_msonable</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">test_is_subclass</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">str</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/testing.py#L68-L99"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.testing.MatSciTest.assert_msonable" title="Link to this definition"></a></dt>
<dd><p>Test if an object is MSONable and verify the contract is fulfilled,
and return the serialized object.</p>
<p>By default, the method tests whether obj is an instance of MSONable.
This check can be deactivated by setting <cite>test_is_subclass</cite> to False.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>obj</strong> (<em>Any</em>) – The object to be checked.</p></li>
<li><p><strong>test_is_subclass</strong> (<em>bool</em>) – Check if object is an instance of MSONable
or its subclasses.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Serialized object.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>str</p>
</dd>
</dl>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.testing.MatSciTest.assert_str_content_equal">
<em class="property"><span class="k"><span class="pre">static</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">assert_str_content_equal</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">actual</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">expected</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">None</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/testing.py#L101-L120"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.testing.MatSciTest.assert_str_content_equal" title="Link to this definition"></a></dt>
<dd><p>Test if two strings are equal, ignoring whitespaces.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>actual</strong> (<em>str</em>) – The string to be checked.</p></li>
<li><p><strong>expected</strong> (<em>str</em>) – The reference string.</p></li>
</ul>
</dd>
<dt class="field-even">Raises<span class="colon">:</span></dt>
<dd class="field-even"><p><strong>AssertionError</strong> – When two strings are not equal.</p>
</dd>
</dl>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.testing.MatSciTest.get_structure">
<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">get_structure</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="pymatgen.core.html#pymatgen.core.structure.Structure" title="pymatgen.core.structure.Structure"><span class="pre">Structure</span></a></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/testing.py#L122-L140"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.testing.MatSciTest.get_structure" title="Link to this definition"></a></dt>
<dd><p>Load a structure from <cite>pymatgen.util.structures</cite>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>name</strong> (<em>str</em>) – Name of the structure file, for example “LiFePO4”.</p>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Structure</p>
</dd>
</dl>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="pymatgen.util.testing.MatSciTest.serialize_with_pickle">
<span class="sig-name descname"><span class="pre">serialize_with_pickle</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">objects</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Any</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">protocols</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Sequence</span><span class="p"><span class="pre">[</span></span><span class="pre">int</span><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">test_eq</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">bool</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><span class="pre">list</span></span></span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/testing.py#L142-L209"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.testing.MatSciTest.serialize_with_pickle" title="Link to this definition"></a></dt>
<dd><p>Test whether the object(s) can be serialized and deserialized with
<cite>pickle</cite>. This method tries to serialize the objects with <cite>pickle</cite> and the
protocols specified in input. Then it deserializes the pickled format
and compares the two objects with the <cite>==</cite> operator if <cite>test_eq</cite>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>objects</strong> (<em>Any</em>) – Object or list of objects.</p></li>
<li><p><strong>protocols</strong> (<em>Sequence</em><em>[</em><em>int</em><em>]</em>) – List of pickle protocols to test.
If protocols is None, HIGHEST_PROTOCOL is tested.</p></li>
<li><p><strong>test_eq</strong> (<em>bool</em>) – If True, the deserialized object is compared
with the original object using the <cite>__eq__</cite> method.</p></li>
</ul>
</dd>
<dt class="field-even">Returns<span class="colon">:</span></dt>
<dd class="field-even"><p>Objects deserialized with the specified protocols.</p>
</dd>
<dt class="field-odd">Return type<span class="colon">:</span></dt>
<dd class="field-odd"><p>list[Any]</p>
</dd>
</dl>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="pymatgen.util.testing.PymatgenTest">
<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">PymatgenTest</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">methodName</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'runTest'</span></span></em><span class="sig-paren">)</span><a class="reference external" href="https://github.com/materialsproject/pymatgen/blob/v2025.6.14/src/pymatgen/core/../util/testing.py#L212-L217"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#pymatgen.util.testing.PymatgenTest" title="Link to this definition"></a></dt>
<dd><p>Bases: <code class="xref py py-class docutils literal notranslate"><span class="pre">TestCase</span></code>, <a class="reference internal" href="#pymatgen.util.testing.MatSciTest" title="pymatgen.util.testing.MatSciTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">MatSciTest</span></code></a></p>
<p>Extends unittest.TestCase with several assert methods for array and str comparison.</p>
<p>Deprecated: please use <cite>MatSciTest</cite> instead (migrate from <cite>unittest</cite> to <cite>pytest</cite>).</p>
<p>Create an instance of the class that will use the named test
method when executed. Raises a ValueError if the instance does
not have a method with the specified name.</p>
</dd></dl>

</section>
<section id="module-pymatgen.util.typing">
<span id="pymatgen-util-typing-module"></span><h2>pymatgen.util.typing module<a class="headerlink" href="#module-pymatgen.util.typing" title="Link to this heading"></a></h2>
<p>This module defines convenience types for type hinting purposes.
Type hinting is new to pymatgen, so this module is subject to
change until best practices are established.</p>
</section>
</section>


           </div>
          </div>
          <footer>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2011, Pymatgen Development Team.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>
